home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UNIXTOOL / GNU / TILEFORTH / TILE / TILE~ / !Tile / doc / Manual < prev    next >
Text File  |  1992-04-26  |  263KB  |  7,987 lines
  1.  
  2.  
  3.  
  4.    August 1, 1990                                               BITFIELDS(3X)
  5.  
  6.  
  7.  
  8.    NAME
  9.      bitfields - bit field manipulation library
  10.  
  11.    SYNOPSIS
  12.      #include bitfields.f83
  13.  
  14.      bitfields
  15.  
  16.    DESCRIPTION
  17.      Allows definition and manipulation of bit fields. The bit field is
  18.      described in a syntax similar to a structure with fields from the least
  19.      significant bit towards the most significant bit. The bit field value is
  20.      manipulated on the data stack and is therefore limited to the width of
  21.      the stack, i.e., 32-bits. The kernel supports the bit field library with
  22.      five functions; "b@", "b!", "f@", "<f@" and "f!". These allow high per-
  23.      formance manipulation of stack oriented bit field data. The functions
  24.      are also defined in forth for other environments.
  25.  
  26.      vocabulary bitfields ( -- )
  27.           Vocabulary for bit field definitions. Include into the search path,
  28.           "context", to allow definition and usage of the bit field library.
  29.  
  30.      : bitfield.type ( -- )
  31.           Marks the beginning of a bit field type structure. Used in the fol-
  32.           lowing form:
  33.           bitfield.type <_b_i_t_f_i_e_l_d-_t_y_p_e-_n_a_m_e> ( -- )
  34.           { <_b_i_t_f_i_e_l_d-_n_a_m_e> }
  35.           bitfield.end
  36.           and to a create bit field variables:
  37.           <bitfield-type-name> <_b_i_t_f_i_e_l_d-_v_a_r_i_a_b_l_e-_n_a_m_e> ( -- addr)
  38.           The bits within the bit field are numbered from 0 to 31 starting
  39.           from right (lsb) to left (msb). The <_b_i_t_f_i_e_l_d-_n_a_m_e> may be gen-
  40.           erated with the words "bit", "bits", "byte", "nibble", and, "word"
  41.           to define the bit field names.
  42.  
  43.      : bits ( width -- )
  44.           Used in the following form:
  45.           <_w_i_d_t_h> bits <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width)
  46.           within a bit field type definition to define field name for an
  47.           arbitrary set of bits.
  48.  
  49.      bitfield.field bit ( -- )
  50.           Used in the following form:
  51.           bit <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width)
  52.           within a bit field type layout definition section to give name to a
  53.           bit at the current position. The bit positions are numbered from 0
  54.           to 31 and right to left within a long number.
  55.  
  56.      bitfield.field nibble ( -- )
  57.           Used in the following form:
  58.           nibble <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width)
  59.           within a bit field type layout section definition to give name to a
  60.           nibble (four bits).
  61.  
  62.  
  63.                                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.    BITFIELDS(3X)                                               August 1, 1990
  71.  
  72.  
  73.      bitfield.field byte ( -- )
  74.           Used in the following form:
  75.           byte <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width)
  76.           within a bit field type layout section definition to give name to a
  77.           byte (eight bits).
  78.  
  79.      bitfield.field word ( -- )
  80.           Used in the following form:
  81.           word <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width)
  82.           within a bit field type layout section definition to give name to a
  83.           word (sixteen bits).
  84.  
  85.      : bitfield.end ( -- )
  86.           Ends the definition of a bit field type. Will give a warning mes-
  87.           sage if the last field position exceeded 32 bits.
  88.  
  89.    INTERNALS
  90.      The _b_i_t_f_i_e_l_d_s vocabulary contains the following private definitions to
  91.      allow definition of fields.
  92.  
  93.      : bitfield.field ( width -- ) private
  94.           Utility function to create additional constant bit field type
  95.           names, other than "bit", "byte", etc.
  96.  
  97.    SEE ALSO
  98.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  99.  
  100.    EXAMPLES
  101.      To create an object pointer bit field structure with fields for type and
  102.      pointer:
  103.  
  104.           #include bitfields.f83
  105.           #include enumerates.f83
  106.  
  107.           bitfields enumerates
  108.  
  109.           bitfield.type OBJECT ( -- )
  110.                2  bits TYPE ( -- pos width)
  111.                30 bits VALUE ( -- pos width)
  112.           bitfield.end
  113.  
  114.      Create an object pointer, access and manipulate its value:
  115.  
  116.           enum.type PRIMITIVE-CLASS ( -- )
  117.                enum SMALL-NUMBER ( -- enum)
  118.                enum BLOCK-POINTER ( -- enum)
  119.                enum OBJECT-HANDLE ( -- enum)
  120.                enum PRIMITIVE ( -- enum)
  121.           enum.end
  122.  
  123.           OBJECT x ( -- addr)
  124.  
  125.           SMALL-NUMBER 0 TYPE f! ( -- 0 | SMALL-NUMBER)
  126.           42 swap VALUE f! ( -- 42 | SMALL-NUMBER)
  127.  
  128.  
  129.    2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.    August 1, 1990                                               BITFIELDS(3X)
  137.  
  138.  
  139.            !
  140.  
  141.    NOTE
  142.      The function list is sorted in logical order.  The type and mode of the
  143.      entries are indicated together with their parameter stack effect.
  144.  
  145.      The bit field definitions require a 32-bit cell size. This library may
  146.      only be directly ported to other 32-bit implementations of the Forth-83
  147.      Standard.
  148.  
  149.    COPYING
  150.      Copyright (C) 1990 Mikael R.K. Patel
  151.  
  152.      Permission is granted to make and distribute verbatim copies of this
  153.      manual provided the copyright notice and this permission notice are
  154.      preserved on all copies.
  155.  
  156.      Permission is granted to copy and distribute modified versions of this
  157.      manual under the conditions for verbatim copying, provided also that the
  158.      section entitled "GNU General Public License" is included exactly as in
  159.      the original, and provided that the entire resulting derived work is
  160.      distributed under the terms of a permission notice identical to this
  161.      one.
  162.  
  163.      Permission is granted to copy and distribute translations of this manual
  164.      into another language, under the above conditions for modified versions,
  165.      except that the section entitled "GNU General Public License" may be
  166.      included in a translation approved by the author instead of in the ori-
  167.      ginal English.
  168.  
  169.    AUTHOR
  170.      Mikael R.K. Patel
  171.      Computer Aided Design Laboratory (CADLAB)
  172.      Department of Computer and Information Science
  173.      Linkoping University
  174.      S-581 83 LINKOPING
  175.      SWEDEN
  176.      Email: mip@ida.liu.se
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.    BITSETS(3X)                                                 August 1, 1990
  203.  
  204.  
  205.  
  206.    NAME
  207.      bitsets - bit vector represented sets definitions
  208.  
  209.    SYNOPSIS
  210.      #include bitsets.f83
  211.  
  212.      bitsets
  213.  
  214.    DESCRIPTION
  215.      Allows definition and manipulation of bit vector represented sets. A set
  216.      may contain maximum of 32 items as it is maintained as a stack item. All
  217.      set operations are performed as logic functions; "and", "or", etc. This
  218.      gives rapid manipulation of small sets.  Most set operations require
  219.      only one logic operation.
  220.  
  221.      : .bitset ( bitset -- ) immediate
  222.           Used in the following form:
  223.           <_b_i_t_s_e_t> .bitset <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e>
  224.           to display the bitset values in the following normal set notation:
  225.           { <_e_n_t_r_i_e_s> }
  226.           The bitset type is required to map the items back to their
  227.           corresponding entries. It maintains the list of items defined in
  228.           the universe set.
  229.  
  230.      : >item ( item -- entry) immediate
  231.           Used in the following form:
  232.           <_i_t_e_m> >item <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( item -- entry)
  233.           to map an item value back to the corresponding entry given the
  234.           bitset type name. The bitset type maintains the list of items
  235.           defined in the universe set.
  236.  
  237.      : ?empty-bitset ( bitset -- bool) macro
  238.           Returns "true" if the bitset is an empty set else "false".
  239.  
  240.      : ?map-bitset ( bitset block[ item -- bool] -- )
  241.           Conditional iterator on a bitset. The block is called for each item
  242.           in the set while the block returns "false". Should the block return
  243.           "true" the iterator is terminated.
  244.  
  245.      : ?member-bitset ( item bitset -- bool) macro
  246.           Returns "true" if the item is a member of the bitset else "false".
  247.  
  248.      : append-bitset ( item bitset1 -- bitset2) macro
  249.           Returns the result of appending the item to the bitset.
  250.  
  251.      : bitset.end ( -- )
  252.           Used in the following form:
  253.           bitset.type <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( -- )
  254.           { item <_b_i_t_s_e_t-_i_t_e_m-_n_a_m_e> ( -- item) }
  255.           bitset.end
  256.           to terminate a bitset type definition. The bitset should not con-
  257.           tain more than 32 items as a set value is represented by a 32-bit
  258.           integer number (on stack).
  259.  
  260.  
  261.    4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.    August 1, 1990                                                 BITSETS(3X)
  269.  
  270.  
  271.      : bitset.type ( -- )
  272.           Used in the following form:
  273.           bitset.type <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( -- )
  274.           { item <_b_i_t_s_e_t-_i_t_e_m-_n_a_m_e> ( -- item) }
  275.           bitset.end
  276.           to initiate the definition of a bitset type. The bitset may contain
  277.           at most 32 items as a set value is represented as a 32-bit integer
  278.           on stack and in memory. The bitset type may be used in the follow-
  279.           ing form:
  280.           <bitset-type-name> <_b_i_t_s_e_t-_v_a_r_i_a_b_l_e-_n_a_m_e> ( -- addr)
  281.           to create a bitset variable (and which acts as a normal "vari-
  282.           able").
  283.  
  284.      vocabulary bitsets ( -- )
  285.           The bitset extension vocabulary. Include into the vocabulary search
  286.           structure, "context", to allow access to this library.
  287.  
  288.      : difference-bitset ( bitset1 bitset2 -- bitset3) macro
  289.           Returns the resulting "bitset3" after removing "bitset2" from
  290.           "bitset1".
  291.  
  292.      constant empty-bitset ( -- bitset)
  293.           Returns the empty bitset. For a bit vector representation of sets
  294.           the empty set the value is zero.
  295.  
  296.      : intersection-bitset ( bitset1 bitset2 -- bitset3) macro
  297.           Returns the intersection, "bitset3", between the sets "bitset2" and
  298.           "bitset1".
  299.  
  300.      : item ( -- )
  301.           Used in the following form:
  302.           bitset.type <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( -- )
  303.           { item <_b_i_t_s_e_t-_i_t_e_m-_n_a_m_e> ( -- item) }
  304.           bitset.end
  305.           to create a bitset item. When the item is used it will return the
  306.           item value on the parameter stack. A bitset may contain at most 32
  307.           items as each item corresponds to an unique bit in a 32-bit integer
  308.           stack element.
  309.  
  310.      : map-bitset ( bitset block[ item -- ] -- )
  311.           Bitset iterator function. The code block is called on each item in
  312.           the bitset. The code block may be created with the extension
  313.           library "blocks". The block will receive the item as parameter.
  314.  
  315.      : remove-bitset ( item bitset1 -- bitset2) macro
  316.           Returns the resulting bitset after removing the item from the
  317.           bitset.
  318.  
  319.      : size-bitset ( bitset -- num)
  320.           Returns the size of the bitset, i.e., the number of items in the
  321.           set.
  322.  
  323.      : union-bitset ( bitset1 bitset2 -- bitset3) macro
  324.           Returns the union, "bitset3", between the sets "bitset2" and
  325.  
  326.  
  327.                                                                             5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.    BITSETS(3X)                                                 August 1, 1990
  335.  
  336.  
  337.           "bitset1".
  338.  
  339.      : { ( -- ) immediate
  340.           Used in the following form:
  341.           { <_i_t_e_m_s> } ( -- bitset)
  342.           to start the definition of a bitset. The brackets should only con-
  343.           tain item entries.
  344.  
  345.      : } ( -- bitset)
  346.           Used in the following form:
  347.           { <_i_t_e_m_s> } ( -- bitset)
  348.           to end a bitset definition. The brackets should only contain item
  349.           entries.
  350.  
  351.    INTERNALS
  352.      Private definitions in the _b_i_t_s_e_t_s vocabulary;
  353.  
  354.      : (.bitset) ( bitset bitset.type -- ) private
  355.           Performs the run-time action of displaying the bitset given the
  356.           mapping set of entries. Compiled by the word ".bitset".
  357.  
  358.      : (>item) ( item bitset.type -- entry) private
  359.           Performs the run-time action of locating an item entry given its
  360.           bitset value. Returns the "entry" pointer or "nil" if not found.
  361.           Compiled by the word ">item".
  362.  
  363.    SEE ALSO
  364.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _m_a_c_r_o_s(_3_X), _b_l_o_c_k_s(_3_X).
  365.  
  366.    NOTE
  367.      The function list is sorted in ASCII order. The type and mode of the
  368.      entry is indicated together with the parameter stack effect.
  369.  
  370.    COPYING
  371.      Copyright (C) 1990 Mikael R.K. Patel
  372.  
  373.      Permission is granted to make and distribute verbatim copies of this
  374.      manual provided the copyright notice and this permission notice are
  375.      preserved on all copies.
  376.  
  377.      Permission is granted to copy and distribute modified versions of this
  378.      manual under the conditions for verbatim copying, provided also that the
  379.      section entitled "GNU General Public License" is included exactly as in
  380.      the original, and provided that the entire resulting derived work is
  381.      distributed under the terms of a permission notice identical to this
  382.      one.
  383.  
  384.      Permission is granted to copy and distribute translations of this manual
  385.      into another language, under the above conditions for modified versions,
  386.      except that the section entitled "GNU General Public License" may be
  387.      included in a translation approved by the author instead of in the ori-
  388.      ginal English.
  389.  
  390.  
  391.  
  392.  
  393.    6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.    August 1, 1990                                                 BITSETS(3X)
  401.  
  402.  
  403.    AUTHOR
  404.      Mikael R.K. Patel
  405.      Computer Aided Design Laboratory (CADLAB)
  406.      Department of Computer and Information Science
  407.      Linkoping University
  408.      S-581 83 LINKOPING
  409.      SWEDEN
  410.      Email: mip@ida.liu.se
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.                                                                             7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.    BLOCKS(3X)                                                  August 1, 1990
  467.  
  468.  
  469.  
  470.    NAME
  471.      blocks - code blocks definition library
  472.  
  473.    SYNOPSIS
  474.      #include blocks.f83
  475.  
  476.      blocks
  477.  
  478.    DESCRIPTION
  479.      Allows definition and execution of code blocks. An alternative to pass-
  480.      ing colon definitions as arguments and creating special control struc-
  481.      tures. Code blocks are used by the _t_i_l_e source code library to pass
  482.      parameters to iterator functions such as "map*" and "?map*". These func-
  483.      tions perform the iteration over collections of data (such as lists,
  484.      queues, ranges and sets) and call the code block on each element in the
  485.      collection.
  486.  
  487.      vocabulary blocks ( -- )
  488.           Vocabulary for code block definitions. Include this library by
  489.           adding the vocabulary to the search set, "context".
  490.  
  491.      : block[ ( -- ) immediate
  492.           Used in the following form:
  493.           block[ ( ... ) ... <_b_l_o_c_k-_d_e_f_i_n_i_t_i_o_n> ... ]; ( -- block)
  494.           Marks the beginning of a code block. Compiles a code block until
  495.           "];" and returns the address to the code block. The code block may
  496.           then be executed using "call". Code blocks may contain definitions
  497.           of other code blocks. Argument binding and local variables are
  498.           allowed in the code block using the "locals" extension but cannot
  499.           use the words "does>" and "exception>" as these require a vocabu-
  500.           lary entry binding.
  501.  
  502.      : ]; ( -- block) immediate
  503.           Used in the following form:
  504.           block[ ( ... ) ... <_b_l_o_c_k-_d_e_f_i_n_i_t_i_o_n> ... ]; ( -- block)
  505.           Marks the end of a code block. Returns a pointer to the code block.
  506.           If the code block is generated within a colon definition the block
  507.           pointer is returned at run-time.
  508.  
  509.      : call ( block  -- )
  510.           Executes a code block. Any parameters used by the code block are
  511.           passed as usual on the parameter stack. Return values are handled
  512.           in the same way.
  513.  
  514.    INTERNALS
  515.      Private definitions in the _b_l_o_c_k_s vocabulary;
  516.  
  517.      field +block ( addr -- block) private
  518.           Field access variable to calculate the offset to an in-line block
  519.           literals within a compiled section of code.
  520.  
  521.  
  522.  
  523.  
  524.  
  525.    8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.    August 1, 1990                                                  BLOCKS(3X)
  533.  
  534.  
  535.    SEE ALSO
  536.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _c_o_m_p_i_l_e_r(_3_X).
  537.  
  538.    EXAMPLES
  539.      An example showing how a function may return a code block which is bound
  540.      to a constant and later called:
  541.  
  542.           : action ( flag -- block)
  543.                 if block[ 10 + ]; else block[ 10 - ]; then
  544.           ;
  545.  
  546.           true action constant delayed-action
  547.  
  548.           32 delayed-action call
  549.  
  550.    NOTE
  551.      The function list is sorted in logical order. The type and mode of the
  552.      entries are indicated together with their parameter stack effect.
  553.  
  554.    WARNING
  555.      The code block may not contain the words "recurse", "tail-recurse",
  556.      "does>" and "exception>" as these require an entry binding, i.e., a
  557.      colon definition.
  558.  
  559.    COPYING
  560.      Copyright (C) 1990 Mikael R.K. Patel
  561.  
  562.      Permission is granted to make and distribute verbatim copies of this
  563.      manual provided the copyright notice and this permission notice are
  564.      preserved on all copies.
  565.  
  566.      Permission is granted to copy and distribute modified versions of this
  567.      manual under the conditions for verbatim copying, provided also that the
  568.      section entitled "GNU General Public License" is included exactly as in
  569.      the original, and provided that the entire resulting derived work is
  570.      distributed under the terms of a permission notice identical to this
  571.      one.
  572.  
  573.      Permission is granted to copy and distribute translations of this manual
  574.      into another language, under the above conditions for modified versions,
  575.      except that the section entitled "GNU General Public License" may be
  576.      included in a translation approved by the author instead of in the ori-
  577.      ginal English.
  578.  
  579.    AUTHOR
  580.      Mikael R.K. Patel
  581.      Computer Aided Design Laboratory (CADLAB)
  582.      Department of Computer and Information Science
  583.      Linkoping University
  584.      S-581 83 LINKOPING
  585.      SWEDEN
  586.      Email: mip@ida.liu.se
  587.  
  588.  
  589.  
  590.  
  591.                                                                             9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.    BLOCKS(3X)                                                  August 1, 1990
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.    10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.    August 1, 1990                                                COMPILER(3X)
  665.  
  666.  
  667.  
  668.    NAME
  669.      compiler - tile kernel compiler support functions
  670.  
  671.    SYNOPSIS
  672.      compiler
  673.  
  674.    DESCRIPTION
  675.      The _c_o_m_p_i_l_e_r vocabulary of the _t_i_l_e forth kernel contains all primitives
  676.      compiled by high level words for control structures and literals. The
  677.      primitives are isolated to a separate vocabulary to minimize dependen-
  678.      cies and increase portability.
  679.  
  680.      code (+loop) ( n -- ) compilation
  681.           Performs the same action as "(loop)" but uses the top of stack
  682.           value as the increment, "n", of the loop index. Checks if the loop
  683.           limit has been exceeded. Compiled by the word "+loop".
  684.  
  685.      code (.") ( -- ) compilation
  686.           Prints the in-line string on the current output stream. Compiled by
  687.           the word "."".
  688.  
  689.      code (;) ( -- ) compilation
  690.           Performs the run-time action of returning from a colon definition.
  691.           Compiled by the word ";".
  692.  
  693.      code (?branch) ( flag -- ) compilation
  694.           Performs the run-time action of conditionally branching in threaded
  695.           code. If the "flag" is zero a branch is performed using a literal
  696.           succeeding this word else the literal is skipped. The branch
  697.           literal is the relative address. Compiled by the words "if",
  698.           "while", "until", and "of".
  699.  
  700.      code (?do) ( end start -- ) compilation
  701.           Performs the run-time action of initializing for a loop block if
  702.           the "start" and "end" index are not equal else skips the block.
  703.           Moves the two parameters, "end" and "start", to the return stack
  704.           and a pointer to the relative address literal succeeding this word
  705.           so that "leave" may be performed in any section of the looped
  706.           block.  Compiled by the word "?do".
  707.  
  708.      code (abort") ( flag -- ) compilation
  709.           Performs the run-time action of checking the error "flag" and if
  710.           non-zero, true, aborts the current computation. Uses an in-line
  711.           string to display an abort message. Compiled by the word "abort"".
  712.  
  713.      code (does>) ( -- ) compilation
  714.           Performs the run-time action of returning from the current colon
  715.           definition and setting the code type of the last defined entry to
  716.           be the code following "(does>)" thus giving it the right run-time
  717.           action. Compiled by the word "does>".
  718.  
  719.      code (branch) ( -- ) compilation
  720.           Performs the run-time action of branching in threaded code. Literal
  721.  
  722.  
  723.                                                                            11
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.    COMPILER(3X)                                                August 1, 1990
  731.  
  732.  
  733.           succeeding this word contains a relative address to the next
  734.           thread. Compiled by the words "else", "again", "endof" and
  735.           "repeat".
  736.  
  737.      code (do) ( end start -- ) compilation
  738.           Performs the run-time action of initializing for a loop block.
  739.           Moves the two parameters, "end" and "start", to the return stack
  740.           and a pointer to the relative address literal succeeding this word
  741.           so that "leave" may be performed in any section of the looped
  742.           block.  Compiled by the word "do".
  743.  
  744.      code (literal) ( -- int) compilation
  745.           Pushes the in-line constant following the threaded code onto the
  746.           parameter stack. Compiled by the words "literal" and "[']".
  747.  
  748.      code (loop) ( -- ) compilation
  749.           Performs the run-time action of incrementing the loop index and
  750.           checking it against the upper limit for the loop. If the index is
  751.           still within the loop limit a branch is performed back to the
  752.           beginning of the loop. The branch offset is stored in-line directly
  753.           after the "(loop)" thread. Compiled by the word "loop".
  754.  
  755.      code <mark ( -- marker) compilation
  756.           Marks the current position in the compilation code stream as a
  757.           position for backwards branch.
  758.  
  759.      code <resolve ( marker -- ) compilation
  760.           Allocates space for and calculates a backward branch offset.
  761.  
  762.      code >mark ( -- marker) compilation
  763.           Allocates space for a branch offset and marks it for forward
  764.           resolving.
  765.  
  766.      code >resolve ( marker -- ) compilation
  767.           Resolves a forward branch offset.
  768.  
  769.      vocabulary compiler ( -- )
  770.           Vocabulary containing the compilation word set. Compiler support,
  771.           compiled words and threading primitives. Include into the vocabu-
  772.           lary search set, "context", to allow access to these extensions.
  773.  
  774.      code thread ( entry -- )
  775.           Used to create threaded code in the dictionary area. Allows code to
  776.           be written without considering the threading principle.
  777.  
  778.      code unthread ( addr -- entry)
  779.           Given a reference to threaded code returns an unthreaded entry
  780.           pointer.
  781.  
  782.    SEE ALSO
  783.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  784.  
  785.  
  786.  
  787.  
  788.  
  789.    12
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.    August 1, 1990                                                COMPILER(3X)
  797.  
  798.  
  799.    EXAMPLES
  800.      A simple definition of "if" and "then" with mode checking:
  801.  
  802.           : if ( flag -- )
  803.                compile (?branch) >mark
  804.           ; compilation immediate
  805.  
  806.           : then ( -- )
  807.                <resolve
  808.           ; compilation immediate
  809.  
  810.    NOTE
  811.      The function list is sorted in ASCII order. The type and mode of the
  812.      entries are indicated together with their parameter stack effect.
  813.  
  814.    WARNING
  815.      Code written using this word set is not directly portable to other forth
  816.      environments.
  817.  
  818.    COPYING
  819.      Copyright (C) 1990 Mikael R.K. Patel
  820.  
  821.      Permission is granted to make and distribute verbatim copies of this
  822.      manual provided the copyright notice and this permission notice are
  823.      preserved on all copies.
  824.  
  825.      Permission is granted to copy and distribute modified versions of this
  826.      manual under the conditions for verbatim copying, provided also that the
  827.      section entitled "GNU General Public License" is included exactly as in
  828.      the original, and provided that the entire resulting derived work is
  829.      distributed under the terms of a permission notice identical to this
  830.      one.
  831.  
  832.      Permission is granted to copy and distribute translations of this manual
  833.      into another language, under the above conditions for modified versions,
  834.      except that the section entitled "GNU General Public License" may be
  835.      included in a translation approved by the author instead of in the ori-
  836.      ginal English.
  837.  
  838.    AUTHOR
  839.      Mikael R.K. Patel
  840.      Computer Aided Design Laboratory (CADLAB)
  841.      Department of Computer and Information Science
  842.      Linkoping University
  843.      S-581 83 LINKOPING
  844.      SWEDEN
  845.      Email: mip@ida.liu.se
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.                                                                            13
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.    DEBUGGER(3X)                                                August 6, 1990
  863.  
  864.  
  865.  
  866.    NAME
  867.      debugger - forth level debugger
  868.  
  869.    SYNOPSIS
  870.      #include debugger.f83
  871.  
  872.      debugger
  873.  
  874.    DESCRIPTION
  875.      The _t_i_l_e forth debugger package. Allows basic black-box tracing of colon
  876.      definitions, break on function call and profiling of function calls. The
  877.      debugger is built on a general advice package so that it may easily be
  878.      extended with addition debugging functions. The advice concept is a
  879.      function may be asked for advice on how to handle a colon definition.
  880.      The trace advice function wraps the function call in printing of the
  881.      stack status and the name of the function.
  882.  
  883.      : *abort* ( -- )
  884.           Abort command in a break point. Will abort the break point inter-
  885.           preter command loop and clear the stacks. Should only be used in a
  886.           break point.
  887.  
  888.      : *call* ( -- )
  889.           Calls the broken function in a break point. Will not return to the
  890.           break point interpreter. The program will continue. Should only be
  891.           used in a break point.
  892.  
  893.      : *execute* ( -- )
  894.           Executes the broken funtion in a break point. Will return to the
  895.           break point interpreter so that the program stack may be inves-
  896.           taged. Should only be used in a break point.
  897.  
  898.      : *profile* ( -- )
  899.           Displays the profile information for a broken function. Should only
  900.           be used in a break point.
  901.  
  902.      : *return* ( -- )
  903.           Returns from a break point. The break point interpreter is left.
  904.  
  905.      : .profile ( -- )
  906.           Scans through the definitions vocabulary, "current", and prints the
  907.           available profile information for advice functions. Displays the
  908.           number of calls and the name of the functions.
  909.  
  910.      : .s ( -- )
  911.           Displays the current parameter stack contents in the format:
  912.           [ <depth> ] <bottom> \ ... \ <top>
  913.           Only the top five elements of the stack are displayed. If more than
  914.           five elements are available is this indicated by the depth and the
  915.           prefix "...".
  916.  
  917.      : : ( -- )
  918.           Redefinition of "colon" to allow easy debugging of "any" code
  919.  
  920.  
  921.    14
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.    August 6, 1990                                                DEBUGGER(3X)
  929.  
  930.  
  931.           definitions without rewriting.
  932.  
  933.      : ?advice ( entry -- bool)
  934.           Used in the following form:
  935.           ' <_e_n_t_r_y> ?advice
  936.           Verifies that the entry passed as a parameter is an advice func-
  937.           tion.
  938.  
  939.      : advice ( action -- )
  940.           Used in the following form:
  941.           ' <_a_d_v_i_c_e-_a_c_t_i_o_n> advice <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n>
  942.           Makes the parameter "action" the advice action for an advice colon
  943.           definition. The colon definition is verified before the assignment
  944.           is performed. The advice action should be a function which receives
  945.           an advice block and performs some action on it. Resets the profile
  946.           information.
  947.  
  948.      : break ( -- )
  949.           Used in the following form:
  950.           break <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n>
  951.           to make an advice colon definition a function with a break point.
  952.           An error message is given if the succeeding symbol is not of
  953.           correct type. When the <advice-colon-definition> is called a break
  954.           command loop is entered. A new interpreter top loop is entered.
  955.           This top loop will accept any forth statement. The commands
  956.           "*abort*", "*call*", "*execute*", "*profile*" and "*return*" should
  957.           be used to control the execution of the broken definition. The word
  958.           "*abort" will abort execution, enpty the stacks and return to the
  959.           normal "interpret" top loop.  The word "*call*" may be used to
  960.           evoke the broken definition and continue execution. The definition
  961.           will not return to the break point interpreter. The command "*exe-
  962.           cute*" performs the same operation but returns to the break point
  963.           interpreter so that the return value and program state may be
  964.           checked before continuing. The word "*profile*" displays the pro-
  965.           file information for the broken definition and last, the word
  966.           "*return*" will leave the break point.
  967.  
  968.      : colon ( -- )
  969.           Used in the following form:
  970.           colon <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n>
  971.           To make an advice colon definition a "normal" function again.  An
  972.           error message is given if the entry is not of correct type.
  973.  
  974.      vocabulary debugger ( -- )
  975.           Vocabulary containing the debugger definitions. Include into the
  976.           vocabulary search set, "context", to allow access to the debugger.
  977.           This vocabulary should come before "forth" in the set.
  978.  
  979.      : tail-recurse ( -- ) compilation immediate
  980.           Redefinition of the tail recursion compilation word to make it work
  981.           correctly in this context.
  982.  
  983.      : trace ( -- )
  984.           Used in the following form:
  985.  
  986.  
  987.                                                                            15
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.    DEBUGGER(3X)                                                August 6, 1990
  995.  
  996.  
  997.           trace <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n>
  998.           To make an advice colon definition a traced function. An error mes-
  999.           sage is given if the succeeding symbol is not of correct type. When
  1000.           the <advice-colon-definition> is later called the advice function
  1001.           with display the name of the definition together with the stack
  1002.           status for both the enter and exit of the call.  Profile informa-
  1003.           tion is also collected.
  1004.  
  1005.    INTERNALS
  1006.      Private definitions in the _d_e_b_u_g_g_e_r vocabulary;
  1007.  
  1008.      ptr +advice ( advice -- addr) private
  1009.           Access field to advice function which is called to handle the code
  1010.           block. The advice function is call with execute thus it is a
  1011.           pointer to an entry. Three predefined advice functions are avail-
  1012.           able for profiling, tracing and break points.
  1013.  
  1014.      ptr +block ( advice -- addr) private
  1015.           Access field to code block of advice colon definition. Stored as a
  1016.           pointer to threaded code.
  1017.  
  1018.      ptr +entry ( advice -- addr) private
  1019.           Access field to entry with advice block. Allows access of entry
  1020.           fields such as name, link, etc. Stored as a pointer to an entry.
  1021.  
  1022.      long +profile ( advice -- addr) private
  1023.           Access field to counter for number of function calls. Basic profil-
  1024.           ing information. Updated by the advice primitives.
  1025.  
  1026.      struct.type ADVICE ( -- ) private
  1027.           The advice structure type. Allows general handling of execution of
  1028.           code definitions. The structure type contains the following private
  1029.           fields; "+advice", "+block", and "+profile".
  1030.  
  1031.      : [advice] ( advice -- ) private
  1032.           Management function to allow interception of function call and cal-
  1033.           ling of advice function.
  1034.  
  1035.      : [break] ( advice -- ) private
  1036.           Primitive advice function which allows a interpreter top loop simi-
  1037.           lar to "interpret", the forth top loop. In this top loop the com-
  1038.           mands "*abort*", "*call*", "*execute*", "*profile*" and "*return*"
  1039.           should be used to control the execution of the advice definition.
  1040.  
  1041.      : [colon] ( advice -- ) private
  1042.           Primitive advice function call for normal function call and incre-
  1043.           ment of profiling counter.
  1044.  
  1045.      : [trace] ( advice -- ) private
  1046.           Primitive advice function for black-box tracing of function calls.
  1047.           The entry and exit of the function call are printed together with
  1048.           the name of the function and the status of the stack.
  1049.  
  1050.  
  1051.  
  1052.  
  1053.    16
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.    August 6, 1990                                                DEBUGGER(3X)
  1061.  
  1062.  
  1063.    SEE ALSO
  1064.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _c_o_m_p_i_l_e_r(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X).
  1065.  
  1066.    EXAMPLES
  1067.      An example showing how to trace and profile a function:
  1068.  
  1069.           #include debugger.f83
  1070.  
  1071.           forth definitions debugger
  1072.  
  1073.           : fac ( n -- n!)
  1074.                dup 0>
  1075.                if dup 1- recurse *
  1076.                else drop 1 then
  1077.           ;
  1078.  
  1079.           trace fac
  1080.           5 fac .
  1081.           .profile
  1082.  
  1083.    NOTE
  1084.      The function list is sorted in ASCII order. The type and mode of the
  1085.      entries are indicated together with their parameter stack effect.
  1086.  
  1087.    WARNING
  1088.      The debugger package will not work correctly on functions which manipu-
  1089.      late the return stack. An advice colon definition must always return to
  1090.      the advice function.
  1091.  
  1092.    COPYING
  1093.      Copyright (C) 1990 Mikael R.K. Patel
  1094.  
  1095.      Permission is granted to make and distribute verbatim copies of this
  1096.      manual provided the copyright notice and this permission notice are
  1097.      preserved on all copies.
  1098.  
  1099.      Permission is granted to copy and distribute modified versions of this
  1100.      manual under the conditions for verbatim copying, provided also that the
  1101.      section entitled "GNU General Public License" is included exactly as in
  1102.      the original, and provided that the entire resulting derived work is
  1103.      distributed under the terms of a permission notice identical to this
  1104.      one.
  1105.  
  1106.      Permission is granted to copy and distribute translations of this manual
  1107.      into another language, under the above conditions for modified versions,
  1108.      except that the section entitled "GNU General Public License" may be
  1109.      included in a translation approved by the author instead of in the ori-
  1110.      ginal English.
  1111.  
  1112.    AUTHOR
  1113.      Mikael R.K. Patel
  1114.      Computer Aided Design Laboratory (CADLAB)
  1115.      Department of Computer and Information Science
  1116.      Linkoping University
  1117.  
  1118.  
  1119.                                                                            17
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.    DEBUGGER(3X)                                                August 6, 1990
  1127.  
  1128.  
  1129.      S-581 83 LINKOPING
  1130.      SWEDEN
  1131.      Email: mip@ida.liu.se
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.    18
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.    August 6, 1990                                              ENUMERATES(3X)
  1193.  
  1194.  
  1195.  
  1196.    NAME
  1197.      enumerates - enumerate variable definitions
  1198.  
  1199.    SYNOPSIS
  1200.      #include enumerates.f83
  1201.  
  1202.      enumerates
  1203.  
  1204.    DESCRIPTION
  1205.      Allows definition of enumerate variable sets. Creates constants with the
  1206.      values zero and upwards.
  1207.  
  1208.      : >enum ( enum -- entry) immediate
  1209.           Used in the following form:
  1210.           <_e_n_u_m-_i_t_e_m-_v_a_l_u_e> >enum <_e_n_u_m-_t_y_p_e-_n_a_m_e> ( enum -- entry)
  1211.           to map an enumerate value back to its corresponding entry. If the
  1212.           entry is not found "nil" returned. The enumerate type maintains a
  1213.           pointer to the list of defined enumerates.
  1214.  
  1215.      : enum ( -- )
  1216.           Used within an "enum.type" definition to declare an enumerate.
  1217.           enum <_e_n_u_m-_i_t_e_m-_n_a_m_e> ( -- enum)
  1218.           The value of the items are zero and upwards.
  1219.  
  1220.      : enum.end ( -- )
  1221.           Used in the following structure:
  1222.           enum.type <_e_n_u_m-_t_y_p_e-_n_a_m_e>
  1223.           { enum <_e_n_u_m-_i_t_e_m-_n_a_m_e> ( -- enum) }
  1224.           enum.end
  1225.           to terminate a "enum.type" definition.
  1226.  
  1227.      : enum.type ( -- )
  1228.           Used in the following structure:
  1229.           enum.type <_e_n_u_m-_t_y_p_e-_n_a_m_e> ( -- )
  1230.           { enum <_e_n_u_m-_i_t_e_m-_n_a_m_e> ( -- enum) }
  1231.           enum.end
  1232.           to start the definition of an enumerate variable and identifiers.
  1233.           The items start with the value zero. The type may later be used to
  1234.           define variables:
  1235.           <enum-type-name> <_e_n_u_m-_v_a_r_i_a_b_l_e-_n_a_m_e> ( -- addr)
  1236.           The enumerate variable corresponds to a normal forth "variable" and
  1237.           may be accessed with the functions "@" and "!".
  1238.  
  1239.      vocabulary enumerates ( -- )
  1240.           Vocabulary for enumerate definitions. Include into the search set,
  1241.           "context", to allow access to this language extension.
  1242.  
  1243.    INTERNALS
  1244.      Private definitions in the _e_n_u_m_e_r_a_t_e_s vocabulary;
  1245.  
  1246.      : (>enum) ( enum enum.type -- entry) private
  1247.           Performs the run-time action of locating an enumerate entry given
  1248.           it's value, "enum", and the enumerate type it is a member of,
  1249.  
  1250.  
  1251.                                                                            19
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.    ENUMERATES(3X)                                              August 6, 1990
  1259.  
  1260.  
  1261.           "enum.type". Compiled by the word ">enum".
  1262.  
  1263.    SEE ALSO
  1264.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  1265.  
  1266.    EXAMPLES
  1267.      The _t_i_l_e forth kernel entries have the following code types:
  1268.  
  1269.           enum.type CODES ( -- )
  1270.                enum CODE ( -- enum)
  1271.                enum COLON ( -- enum)
  1272.                enum VARIABLE ( -- enum)
  1273.                enum CONSTANT ( -- enum)
  1274.                enum VOCABULARY ( -- enum)
  1275.                enum CREATE ( -- enum)
  1276.                enum USER ( -- enum)
  1277.                enum LOCAL ( -- enum)
  1278.                enum FORWARD ( -- enum)
  1279.                enum FIELD ( -- enum)
  1280.                enum EXCEPTION ( -- enum)
  1281.           enum.end
  1282.  
  1283.    NOTE
  1284.      The function list is sorted in ASCII order. The type and mode of the
  1285.      entry is indicated together with the parameter stack effect.
  1286.  
  1287.    COPYING
  1288.      Copyright (C) 1990 Mikael R.K. Patel
  1289.  
  1290.      Permission is granted to make and distribute verbatim copies of this
  1291.      manual provided the copyright notice and this permission notice are
  1292.      preserved on all copies.
  1293.  
  1294.      Permission is granted to copy and distribute modified versions of this
  1295.      manual under the conditions for verbatim copying, provided also that the
  1296.      section entitled "GNU General Public License" is included exactly as in
  1297.      the original, and provided that the entire resulting derived work is
  1298.      distributed under the terms of a permission notice identical to this
  1299.      one.
  1300.  
  1301.      Permission is granted to copy and distribute translations of this manual
  1302.      into another language, under the above conditions for modified versions,
  1303.      except that the section entitled "GNU General Public License" may be
  1304.      included in a translation approved by the author instead of in the ori-
  1305.      ginal English.
  1306.  
  1307.    AUTHOR
  1308.      Mikael R.K. Patel
  1309.      Computer Aided Design Laboratory (CADLAB)
  1310.      Department of Computer and Information Science
  1311.      Linkoping University
  1312.      S-581 83 LINKOPING
  1313.      SWEDEN
  1314.      Email: mip@ida.liu.se
  1315.  
  1316.  
  1317.    20
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.    August 6, 1990                                              ENUMERATES(3X)
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.                                                                            21
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.    EXCEPTIONS(3X)                                              August 6, 1990
  1391.  
  1392.  
  1393.  
  1394.    NAME
  1395.      exceptions - tile kernel error handling functions
  1396.  
  1397.    SYNOPSIS
  1398.      forth
  1399.  
  1400.    DESCRIPTION
  1401.      The _t_i_l_e kernel word set for support of exception definition and manage-
  1402.      ment.  Exceptions may be signaled by the environment (such as arithmetic
  1403.      or memory segmentation error) or raised by functions in an application.
  1404.      The _t_i_l_e forth virtual machine maintains exception frames. An exception
  1405.      frame is a copy of the state of the virtual machine when a colon defini-
  1406.      tion with error handling is entered. This state may be used to restore
  1407.      the virtual machine when an error occurs.
  1408.  
  1409.      An exception block is part of a colon definition and marked in a syntax
  1410.      style similar to the high level management block "does>". This block
  1411.      will receive the error flag (signal or exception) and the machine is
  1412.      restored if an error occurs. Exception blocks may be nested. A function
  1413.      with error handling may call functions with error handling and so on.
  1414.      The cost of an error handling block corresponds to the cost of saving
  1415.      all virtual machine registers in an exception block on the return stack.
  1416.  
  1417.      Exceptions should be used to simplify control structures where the pro-
  1418.      grammer is otherwise forced to mix the control structure for the algo-
  1419.      rithm with the control structure for the error situations.
  1420.  
  1421.      code exception ( --- )
  1422.           Used in the following form:
  1423.           exception <_e_x_c_e_p_t_i_o_n-_n_a_m_e> ( -- exception)
  1424.           to define an exception symbol. An exception may be raised using:
  1425.           <_e_x_c_e_p_t_i_o_n-_n_a_m_e> raise
  1426.           The defined "exception" returns a pointer to the entry on the
  1427.           parameter stack when used and may be directly displayed with the
  1428.           word ".name".
  1429.  
  1430.      code exception> ( [signal] or [exception] -- ) compilation immediate
  1431.           Used within a colon definition to mark the beginning of the excep-
  1432.           tion section of the definition:
  1433.           : <_n_a_m_e> ( ... )
  1434.           ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ...
  1435.           exception> ( [signal] or [exception] -- )
  1436.           ... <_e_r_r_o_r-_h_a_n_d_l_i_n_g> ...
  1437.           ;
  1438.           If an error occurs or an "exception" is raised during the execution
  1439.           of the code definition section the control is past to the latest
  1440.           exception block, and the signal number or the exception is past as
  1441.           a parameter. The status of the stacks are restored to the situation
  1442.           before the execution of the most recent definition with an excep-
  1443.           tion block. To pass the exception upwards, to the next exception
  1444.           block, the function "raise" should be used.
  1445.  
  1446.      vocabulary exceptions ( -- )
  1447.  
  1448.  
  1449.    22
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.    August 6, 1990                                              EXCEPTIONS(3X)
  1457.  
  1458.  
  1459.           Vocabulary containing the exception management definitions.  Allows
  1460.           definitions of forth level capturing of errors. Uses a syntax style
  1461.           similar Ada to make the beginning of an exception section within a
  1462.           colon definition. Include into the vocabulary search structure,
  1463.           "context", to allow access of these extensions.
  1464.  
  1465.      code raise ( [signal] or [exception] -- )
  1466.           Activates a exceptions handler with signal identification number or
  1467.           an exception symbol. If an exception frame exists the virtual
  1468.           machine is restored to this state and resumed. The default action
  1469.           taken if no exception block is available is abort with a message
  1470.           about the task, and the name of the signal or exception. Signals
  1471.           are generated from the run-time environment.
  1472.  
  1473.    INTERNALS
  1474.      The following words of the exception extension are mainly used to imple-
  1475.      ment the error handling mechanism.
  1476.  
  1477.      code (exception;) ( -- ) compilation
  1478.           Unlinks the current exception frame from the return stack and
  1479.           returns from a colon definition. Compiled by the word "exception>".
  1480.  
  1481.      code (exception>) ( addr -- ) compilation
  1482.           Builds an exception frame on the return stack and jumps to the
  1483.           address given as a parameter, "addr". A colon definition with an
  1484.           exception block will have a "code" field with a pointer to code
  1485.           section with this word. The virtual machine will push a pointer to
  1486.           the parameter field, "addr", and call the exception section.
  1487.  
  1488.      code (exceptionunlink;) ( -- ) compilation
  1489.           Unlinks the exception frame and argument frame from the stacks and
  1490.           returns from the colon definitions. Compiled by the word "excep-
  1491.           tion>" when a local frame has been used.
  1492.  
  1493.    SEE ALSO
  1494.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  1495.  
  1496.    EXAMPLES
  1497.      An example showing how to redefine the arithmetic division operation for
  1498.      exception and retry:
  1499.  
  1500.           exceptions
  1501.  
  1502.           exception zero-division ( -- exception)
  1503.  
  1504.           : div ( x y -- z)
  1505.                dup 0= if zero-division raise else / then
  1506.           ;
  1507.  
  1508.           : use-div ( x y -- z)
  1509.                div
  1510.           exception> ( x y exception -- )
  1511.                case
  1512.                     zero-division of drop endof
  1513.  
  1514.  
  1515.                                                                            23
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.    EXCEPTIONS(3X)                                              August 6, 1990
  1523.  
  1524.  
  1525.                     raise ( pass exception upwards)
  1526.                endcase
  1527.  
  1528.    NOTE
  1529.      The function list is sorted in ASCII order. The type and mode of the
  1530.      entry is indicated together with the parameter stack effect.
  1531.  
  1532.    COPYING
  1533.      Copyright (C) 1990 Mikael R.K. Patel
  1534.  
  1535.      Permission is granted to make and distribute verbatim copies of this
  1536.      manual provided the copyright notice and this permission notice are
  1537.      preserved on all copies.
  1538.  
  1539.      Permission is granted to copy and distribute modified versions of this
  1540.      manual under the conditions for verbatim copying, provided also that the
  1541.      section entitled "GNU General Public License" is included exactly as in
  1542.      the original, and provided that the entire resulting derived work is
  1543.      distributed under the terms of a permission notice identical to this
  1544.      one.
  1545.  
  1546.      Permission is granted to copy and distribute translations of this manual
  1547.      into another language, under the above conditions for modified versions,
  1548.      except that the section entitled "GNU General Public License" may be
  1549.      included in a translation approved by the author instead of in the ori-
  1550.      ginal English.
  1551.  
  1552.    AUTHOR
  1553.      Mikael R.K. Patel
  1554.      Computer Aided Design Laboratory (CADLAB)
  1555.      Department of Computer and Information Science
  1556.      Linkoping University
  1557.      S-581 83 LINKOPING
  1558.      SWEDEN
  1559.      Email: mip@ida.liu.se
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.    24
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.    August 1, 1990                                                   FLOAT(3X)
  1589.  
  1590.  
  1591.  
  1592.    NAME
  1593.      float - tile kernel floating point arithmetic functions
  1594.  
  1595.    SYNOPSIS
  1596.      float
  1597.  
  1598.    DESCRIPTION
  1599.      The _t_i_l_e forth kernel extends the Forth-83 Standard with arithmetic
  1600.      functions for 32-bit floating point numbers. When the "float" vocabulary
  1601.      is used floating point numbers will be recognized by "interpret", the
  1602.      kernel compiler and interpreter. The function "?float" is the "float"
  1603.      recognizer function.
  1604.  
  1605.      code ?float ( str -- [str false] or [f1 true]) recognizer
  1606.           Given a null-terminated string, "str", scans for a 32-bit floating
  1607.           point number. Returns the value and "true" else the string and
  1608.           "false". This word is the "float" vocabulary literal recognizer
  1609.           function. The function will also recognize the symbols "Infinity",
  1610.           "-Infinity", and "NaN" (not a number) which are defined by the IEEE
  1611.           single precision floating point number system.
  1612.  
  1613.      code 1/f ( f1 -- f2)
  1614.           "f2" is the 32-bit floating point result of dividing one by "f1".
  1615.  
  1616.      code f* ( f1 f2 -- f3)
  1617.           "f3" is the 32-bit floating point product of "f1" and "f2".
  1618.  
  1619.      code f+ ( f1 f2 -- f3)
  1620.           "f3" is the 32-bit floating point arithmetic sum of "f1" and "f2".
  1621.  
  1622.      code f- ( f1 f2 -- f3)
  1623.           "f3" is the 32-bit floating point result of subtracting "f2" from
  1624.           "f1".
  1625.  
  1626.      code f. ( f1 -- )
  1627.           The 32-bit floating point number "f1" is displayed in the standard
  1628.           format on the current output stream.
  1629.  
  1630.      code f/ ( f1 f2 -- f3)
  1631.           "f3" is the 32-bit floating point number the quotient of "f1"
  1632.           divided by the divisor "f2". An error condition results if the
  1633.           divisor is zero.
  1634.  
  1635.      code f>i ( f1 -- i1)
  1636.           The 32-bit floating point number "f1" is converted to a 32-bit
  1637.           integer.
  1638.  
  1639.      vocabulary float ( -- )
  1640.           The floating pointer number extension vocabulary. Include into the
  1641.           vocabulary search set, "context", to allow access to these exten-
  1642.           sions.
  1643.  
  1644.      code fnegate ( f1 -- f2)
  1645.  
  1646.  
  1647.                                                                            25
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.    FLOAT(3X)                                                   August 1, 1990
  1655.  
  1656.  
  1657.           "f2" is the negated value of the floating point value "f1", i.e.,
  1658.           the difference of zero less "f1".
  1659.  
  1660.      code i>f ( i1 -- f1)
  1661.           The 32-bit integer "i1" is converted to a 32-bit floating point
  1662.           number, "f1".
  1663.  
  1664.    SEE ALSO
  1665.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  1666.  
  1667.    NOTE
  1668.      The function list is sorted in ASCII order. The type and mode of the
  1669.      entries are indicated together with their parameter stack effect.
  1670.  
  1671.    COPYING
  1672.      Copyright (C) 1990 Mikael R.K. Patel
  1673.  
  1674.      Permission is granted to make and distribute verbatim copies of this
  1675.      manual provided the copyright notice and this permission notice are
  1676.      preserved on all copies.
  1677.  
  1678.      Permission is granted to copy and distribute modified versions of this
  1679.      manual under the conditions for verbatim copying, provided also that the
  1680.      section entitled "GNU General Public License" is included exactly as in
  1681.      the original, and provided that the entire resulting derived work is
  1682.      distributed under the terms of a permission notice identical to this
  1683.      one.
  1684.  
  1685.      Permission is granted to copy and distribute translations of this manual
  1686.      into another language, under the above conditions for modified versions,
  1687.      except that the section entitled "GNU General Public License" may be
  1688.      included in a translation approved by the author instead of in the ori-
  1689.      ginal English.
  1690.  
  1691.    AUTHOR
  1692.      Mikael R.K. Patel
  1693.      Computer Aided Design Laboratory (CADLAB)
  1694.      Department of Computer and Information Science
  1695.      Linkoping University
  1696.      S-581 83 LINKOPING
  1697.      SWEDEN
  1698.      Email: mip@ida.liu.se
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.    26
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.    April 11, 1991                                                   FORTH(3X)
  1721.  
  1722.  
  1723.  
  1724.    NAME
  1725.      forth - forth-83 standard word set and tile forth kernel extensions
  1726.  
  1727.    SYNOPSIS
  1728.      forth
  1729.  
  1730.    DESCRIPTION
  1731.      The required word set of Forth-83 Standard excluding the block file word
  1732.      set and the _t_i_l_e forth kernel extensions. Each "word" (function, pro-
  1733.      cedure, variable, etc) is described with its stack action, parameters,
  1734.      and return values and its code type. The format of the glossary list is:
  1735.      <type> <name> ( <stack-effect> ) [ <mode> ]
  1736.      The <stack-effect> describes the parameter and return values for the
  1737.      word in the following format:
  1738.      ( <arguments> -- <returns>)
  1739.      The arguments and return values are given from left to right with the
  1740.      deepest stack value first. Symbolic names are often used for the argu-
  1741.      ments while the return values are often only described by data type.
  1742.  
  1743.      The optional <mode> may define how the word is interpreted and when it
  1744.      is visible. The mode "immediate" marks the word as always executed. The
  1745.      mode "execution" reduces the words visibility to only execution, i.e.,
  1746.      interpretation, mode. The mode "compilation" reduces the words visibil-
  1747.      ity to only compilation mode. Last, the mode "private" marks the words
  1748.      as only visible in the vocabulary where it is defined. Additional modes
  1749.      are added by other _t_i_l_e forth extensions.
  1750.  
  1751.      The list of required words in the Forth-83 Standard are described in the
  1752.      following sub-sections; "Stack Manipulation", "Memory Access", "Logic",
  1753.      "Arithmetic", "Comparison", "Numeric Conversion", "Control Structures",
  1754.      "Terminal Input/Output", "Interpreter", "Vocabulary", and "Defining
  1755.      Words". Each sub-section is sorted in ASCII order.
  1756.  
  1757.      Stack Manipulation
  1758.  
  1759.      The Forth-83 Standard parameter and return stack manipulation functions.
  1760.      The _t_i_l_e forth kernel also supports the double number stack manipulation
  1761.      extension.
  1762.  
  1763.      code -rot ( x y z -- z x y)
  1764.           The top three stack entries are rotated, forcing the top to become
  1765.           the deepest of the three.
  1766.  
  1767.      code 2>r ( x y -- ) compilation
  1768.           Double "to-r". "x" and "y" are transferred to the return stack.
  1769.  
  1770.      code 2drop ( x y -- )
  1771.           Double "drop". "x" and "y" are dropped.
  1772.  
  1773.      code 2dup ( x1 y1 -- x1 y1 x1 y1)
  1774.           Double "dup". The first pair is copied.
  1775.  
  1776.      code 2over (x1 y1 x2 y2 -- x1 y1 x2 y2 x1 y1)
  1777.  
  1778.  
  1779.                                                                            27
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.    FORTH(3X)                                                   April 11, 1991
  1787.  
  1788.  
  1789.           Double "over". The second pair is copied.
  1790.  
  1791.      code 2r> ( -- x y) compilation
  1792.           Double "from-r". "x" and "y" are removed from the return stack and
  1793.           transferred to the data stack.
  1794.  
  1795.      code 2rot ( x1 y1 x2 y2 x3 y3 -- x2 y2 x3 y3 x1 y1)
  1796.           Double "rot". The three pairs change places.
  1797.  
  1798.      code 2swap ( x1 y1 x2 y2 -- x2 y2 x1 y1)
  1799.           Double "swap". The two pairs change places.
  1800.  
  1801.      code >r ( x -- ) compilation
  1802.           Transfer "x" to the return stack.
  1803.  
  1804.      code ?dup ( x -- [x x] or [x])
  1805.           Duplicate "x" if it is non-zero.
  1806.  
  1807.      code depth ( -- +n)
  1808.           "+n" is the number of values contained in the data stack before
  1809.           "+n" was placed on the stack.
  1810.  
  1811.      code drop ( x -- )
  1812.           "x" is removed from the stack.
  1813.  
  1814.      code dup ( x -- x x)
  1815.           Duplicate "x".
  1816.  
  1817.      code nip ( x y -- y)
  1818.           The second stack element "x" is removed.
  1819.  
  1820.      code over ( x y -- x y x)
  1821.           A copy of "x" is made and moved over "y".
  1822.  
  1823.      code pick ( +n -- x)
  1824.           "x" is a copy of the "+n"-th stack element, not counting "+n"
  1825.           itself. [0..depth-1]
  1826.           "0 pick" is equivalent to "dup"
  1827.           "1 pick" is equivalent to "over"
  1828.  
  1829.      code r> ( -- x) compilation
  1830.           "x" is removed from the return stack and transferred to the data
  1831.           stack.
  1832.  
  1833.      code r@ ( -- x) compilation
  1834.           "x" is a copy of the top of the return stack.
  1835.  
  1836.      code roll ( +n -- )
  1837.           The "+n"-th stack value, not counting "+n" itself is first removed
  1838.           and then transferred to the top of the stack, moving the remaining
  1839.           values into the vacated position. The parameter should be in the
  1840.           interval: [0..depth-1].
  1841.           "0 roll" is a null operation
  1842.           "1 roll" is equivalent to "swap"
  1843.  
  1844.  
  1845.    28
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.    April 11, 1991                                                   FORTH(3X)
  1853.  
  1854.  
  1855.           "2 roll" is equivalent to "rot"
  1856.  
  1857.      code rot ( x y z -- y z x)
  1858.           The top three stack entries are rotated, bringing the deepest to
  1859.           the top.
  1860.  
  1861.      code swap ( x y -- y x)
  1862.           The top two stack entries are exchanged.
  1863.  
  1864.      code tuck ( x y -- y x y)
  1865.           A copy of "y" is tucked under "x".
  1866.  
  1867.      Memory Access
  1868.  
  1869.      The Forth-83 Standard memory and data access word set. The _t_i_l_e forth
  1870.      kernel extends the Forth-83 Standard with additional access functions
  1871.      for bit testing and bit field access. All access to memory is achieved
  1872.      through this word set.
  1873.  
  1874.      code ! ( 32b addr -- )
  1875.           The postfix assignment operator. Store "32b" at "addr".
  1876.  
  1877.      code +! ( x1 addr -- )
  1878.           "x1" is added to the value at "addr" using the convention for "+".
  1879.           The value at "addr" is assumed to be of size "cell".  The sum
  1880.           replaces the original value at "addr".
  1881.  
  1882.      code -match ( addr1 addr2 n -- bool)
  1883.           Matches the strings at address "addr1" and "addr2" of length "n" at
  1884.           the parameter addresses. Returns "false" if the strings are equal
  1885.           else "true". If the length "n" is zero the function will return
  1886.           "true".
  1887.  
  1888.      code -trailing ( addr +n1 -- addr +n2)
  1889.           The character counter "+n1" of a text string beginning at "addr" is
  1890.           adjusted to exclude trailing spaces. If "+n1" is zero, then "+n2"
  1891.           is zero. If the entire string consists of spaces, then "+n2" is
  1892.           zero.
  1893.  
  1894.      code <c@ ( addr -- 8b)
  1895.           "8b" is the value at "addr". The value is sign extended to the
  1896.           stack (cell) width.
  1897.  
  1898.      code <f@ ( x p w -- y)
  1899.           Field access within a 32-bit quantity. "y" are the bits within "x"
  1900.           at position "p" and with a bit field width, "w". Bits positions are
  1901.           counted from right to left starting with zero. A field is defined
  1902.           from a position and upwards. The result "y" is sign extended.
  1903.  
  1904.      code <w@ ( addr -- 16b)
  1905.           "16b" is the value at "addr". The value is sign extended to the
  1906.           stack (cell) width.
  1907.  
  1908.      code @ ( addr -- 32b)
  1909.  
  1910.  
  1911.                                                                            29
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.    FORTH(3X)                                                   April 11, 1991
  1919.  
  1920.  
  1921.           "32b" is the value at "addr". Primary variable value access func-
  1922.           tion.
  1923.  
  1924.      code b! ( x y p -- z)
  1925.           Returns "z", the result of setting the bit at position "p" in "y"
  1926.           according to the value of "x". The bit is set to zero if "x" is
  1927.           zero else one.
  1928.  
  1929.      code b@ ( x p -- y)
  1930.           Returns "true" if the bit a position "p" in "x" is one else
  1931.           "false".
  1932.  
  1933.      code bounds ( addr1 n -- addr2 addr1)
  1934.           Converts vector address and size to boundary address suitable for a
  1935.           "do"-loop. "addr2" is the end address of the vector, i.e., the sum
  1936.           of "addr1" and "n".
  1937.  
  1938.      code c! ( 8b addr -- )
  1939.           The postfix assignment operator. Store "8b" at "addr".
  1940.  
  1941.      code c@ ( addr -- 8b)
  1942.           "8b" is the value at "addr". The value is not sign extended.
  1943.  
  1944.      code cmove ( addr1 addr2 u -- )
  1945.           Move the "u" bytes at address "addr1" to "addr2". The byte at
  1946.           "addr1" is moved first, proceeding toward high memory.  If "u" is
  1947.           zero nothing is moved.
  1948.  
  1949.      code cmove> ( addr1 addr2 u -- )
  1950.           Move the "u" bytes at address "addr1" to "addr2". The move begins
  1951.           by moving the byte at ("addr1"+"u"-1) to ("addr2"+"u"-1) and
  1952.           proceeds to successively lower addresses for "u" bytes.  If "u" is
  1953.           zero nothing is moved. Useful for sliding a string towards higher
  1954.           addresses.
  1955.  
  1956.      code count ( addr1 -- addr2 +n)
  1957.           "addr2" is "addr1"+1 and "+n" is the length of the counted string
  1958.           at "addr1". The byte "addr1" contains the byte count "+n". Range of
  1959.           "+n" is [0..255].
  1960.  
  1961.      code f! ( x y p w -- z)
  1962.           Inserts the value of "x" into "y" at the bit field which is defined
  1963.           by the position "p" and with the width "w". The value "x" is
  1964.           shifted and masked into "y" to form the result "z".
  1965.  
  1966.      code f@ ( x p w -- y)
  1967.           Field access within a 32-bit quantity. "y" are the bits within "x"
  1968.           at position "p" and with a bit field width, "w". Bits positions are
  1969.           counted from right to left starting with zero. A field is defined
  1970.           from a position and upwards.
  1971.  
  1972.      code fill ( addr u 8b -- )
  1973.           "u" bytes of memory beginning at "addr" are set to "8b".  No action
  1974.           is taken is "u" is zero.
  1975.  
  1976.  
  1977.    30
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.    April 11, 1991                                                   FORTH(3X)
  1985.  
  1986.  
  1987.      code w! ( 16b addr -- )
  1988.           The postfix assignment operator. Store "16b" at "addr".
  1989.  
  1990.      code w@ ( addr -- 16b)
  1991.           "16b" is the value at "addr". The value is not sign extended.
  1992.  
  1993.      Logic
  1994.  
  1995.      The Forth-83 Standard logic functions. The _t_i_l_e forth kernel extends the
  1996.      basic function set with boolean constants and a boolean conversion func-
  1997.      tion. All logic functions manipulate their parameters bit-by-bit.
  1998.  
  1999.      code and ( 32b1 32b2 -- 32b3)
  2000.           "32b3" is the bit-by-bit logical and of "32b1" and "32b2".
  2001.  
  2002.      code boolean ( n -- bool)
  2003.           Maps numerical value to a boolean value, "true" or "false".  Non-
  2004.           zero values are mapped to "true" and zero to "false".
  2005.  
  2006.      constant false ( -- 0)
  2007.           The constant "false" represented by the value zero.
  2008.  
  2009.      code or ( 32b1 32b2 -- 32b3)
  2010.           "32b3" is the bit-by-bit inclusive-or of "32b1" with "32b2".
  2011.  
  2012.      code not ( 32b1 -- 32b2)
  2013.           "32b2" is the one's complements of "32b1".
  2014.  
  2015.      constant true ( -- -1)
  2016.           The constant "true" represented by the value minus one.
  2017.  
  2018.      code xor ( 32b1 32b2 -- 32b3)
  2019.           "32b3" is the bit-by-bit exclusive-or of "32b1" with "32b2".
  2020.  
  2021.      Arithmetic
  2022.  
  2023.      The Forth-83 Standard arithmetic word set. The _t_i_l_e forth kernel extends
  2024.      the Forth-83 Standard with arithmetic functions for shifting and addi-
  2025.      tional numeric constants. Double number width arithmetic function such
  2026.      as "d+" and "dnegate" are not implemented as _t_i_l_e forth is a 32-bit
  2027.      implementation. Arithmetic errors are caught by the _t_i_l_e forth kernel
  2028.      and passed to the application as signals. An exception block may be used
  2029.      to catch the signal.
  2030.  
  2031.      code * ( w1 w2 -- w3)
  2032.           "w3" is the least-significant 32 bits of the arithmetic product of
  2033.           "w1" times and "w2".
  2034.  
  2035.      code */ ( w1 w2 w3 -- w4)
  2036.           "w1" is first multiplied by "w2" producing an intermediate 32-bit
  2037.           result. "w4" is the floor of the quotient of the intermediate 32-
  2038.           bit result divided by the divisor "w3". The product of "w1" times
  2039.           "w2" is maintained as an intermediate 32-bit result for greater
  2040.           precision then the otherwise equivalent sequence: "w1 w2 * w3 /".
  2041.  
  2042.  
  2043.                                                                            31
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.    FORTH(3X)                                                   April 11, 1991
  2051.  
  2052.  
  2053.           An error condition results if the divisor is zero and an exception
  2054.           is raised.
  2055.  
  2056.      code */mod ( w1 w2 w3 -- w4 w5)
  2057.           "w1" is first multiplied by "w2" producing an intermediate 32-bit
  2058.           result. "w4" is the remainder and "w5" is the floor of the quotient
  2059.           of the intermediate 32-bit result divided by the divisor "w3". A
  2060.           32-bit intermediate product is used as for "*/". "w4" has the same
  2061.           sign as "w3" or is zero. An error condition results if the divisor
  2062.           is zero and an exception is raised.
  2063.  
  2064.      code + ( w1 w2 -- w3)
  2065.           "w3" is the arithmetic sum of "w1" and "w2".
  2066.  
  2067.      code - ( w1 w2 -- w3)
  2068.           "w3" is the result of subtracting "w2" from "w1".
  2069.  
  2070.      constant -1 ( -- -1)
  2071.           Constant minus one.
  2072.  
  2073.      constant -2 ( -- -2)
  2074.           Constant minus two.
  2075.  
  2076.      constant -4 ( -- -4)
  2077.           Constant minus four.
  2078.  
  2079.      code / ( w1 w2 -- w3)
  2080.           "w3" is the floor of the quotient of "w1" divided by the divisor
  2081.           "w2". An error condition results if the divisor is zero.
  2082.  
  2083.      code /mod ( w1 w2 -- w3 w4)
  2084.           "w3" is the remainder and "w4" the floor of the quotient of "w1"
  2085.           divided by the divisor "w2". "w3" has the same sign as "w2" or is
  2086.           zero. An error condition results if the divisor is zero and an
  2087.           exception is raised.
  2088.  
  2089.      constant 0 ( -- 0)
  2090.           Constant zero.
  2091.  
  2092.      constant 1 ( -- 1)
  2093.           Constant one.
  2094.  
  2095.      code 1+ ( w1 -- w2)
  2096.           "w2" is the result of adding one to "w1" according to the operation
  2097.           of "+".
  2098.  
  2099.      code 1- ( w1 -- w2)
  2100.           "w2" is the result of subtracting one to "w1" according to the
  2101.           operation of "-".
  2102.  
  2103.      constant 2 ( -- 2)
  2104.           Constant two.
  2105.  
  2106.      code 2* ( n1 -- n2)
  2107.  
  2108.  
  2109.    32
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.    April 11, 1991                                                   FORTH(3X)
  2117.  
  2118.  
  2119.           "n2" is the result of arithmetically shifting "n1" left one bit.
  2120.           The sign is included in the shift and remains unchanged.
  2121.  
  2122.      code 2+ ( w1 -- w2)
  2123.           "w2" is the result of adding two to "w1" according to the operation
  2124.           of "+".
  2125.  
  2126.      code 2- ( w1 -- w2)
  2127.           "w2" is the result of subtracting two to "w1" according to the
  2128.           operation of "-".
  2129.  
  2130.      code 2/ ( n1 -- n2)
  2131.           "n2" is the result of arithmetically shifting "n1" right one bit.
  2132.           The sign is included in the shift and remains unchanged.
  2133.  
  2134.      constant 4 ( -- 4)
  2135.           Constant four.
  2136.  
  2137.      code << ( n1 n2 -- n3)
  2138.           "n3" is the result of logically shifting "n1" left "n2" steps.
  2139.  
  2140.      code >> ( n1 n2 -- n3)
  2141.           "n3" is the result of logically shifting "n1" right "n2" steps.
  2142.  
  2143.      code abs ( n -- u)
  2144.           "u" is the absolute value of "n".
  2145.  
  2146.      code max ( n1 n2 -- n3)
  2147.           "n3" is the greater of "n1" and "n2" according to the operation of
  2148.           ">".
  2149.  
  2150.      code min ( n1 n2 -- n3)
  2151.           "n3" is the lesser of "n1" and "n2" according to the operation of
  2152.           "<".
  2153.  
  2154.      code mod ( n1 n2 -- n3)
  2155.           "n3" is the remainder after dividing "n1" by divisor "n2".  "n3"
  2156.           has the same sign as "n2" or is zero. An error condition results if
  2157.           the divisor is zero or if the quotient falls outside of the numeri-
  2158.           cal range.
  2159.  
  2160.      code negate ( n1 -- n2)
  2161.           "n2" is the two's complement of "n1", i.e., the difference of zero
  2162.           less "n1".
  2163.  
  2164.      constant nil ( -- 0)
  2165.           Constant for a nil pointer.
  2166.  
  2167.      code um* ( u1 u2 -- u3)
  2168.           "u3" is the unsigned product of "u1" times "u2". All values and
  2169.           arithmetic are unsigned.
  2170.  
  2171.      code um/mod ( u1 u2 -- u3 u4)
  2172.           "u3" is the remainder and "u4" is the floor of the quotient after
  2173.  
  2174.  
  2175.                                                                            33
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.    FORTH(3X)                                                   April 11, 1991
  2183.  
  2184.  
  2185.           dividing "u1" by the divisor "u2". All values and arithmetic are
  2186.           unsigned. An error condition results if the divisor is zero or if
  2187.           the quotient lies outside the numerical range.
  2188.  
  2189.      Comparison
  2190.  
  2191.      The Forth-83 Standard comparison word set. The _t_i_l_e forth kernel extends
  2192.      the standard with an integer range test function.  The kernel does not
  2193.      implement double number comparison functions.  Boolean values "true" and
  2194.      "false" are represented with "-1" and "0".
  2195.  
  2196.      code 0< ( n -- bool)
  2197.           Returns "true" if "n" is less than zero (negative).
  2198.  
  2199.      code 0= ( w -- bool)
  2200.           Returns "true" if "w" is zero.
  2201.  
  2202.      code 0> ( n -- bool)
  2203.           Returns "true" if "n" is greater than zero.
  2204.  
  2205.      code < ( n1 n2 -- bool)
  2206.           Returns "true" if "n1" is less than "n2".
  2207.  
  2208.      code = ( w1 w2 -- bool)
  2209.           Returns "true" if "w1" is equal to "w2"
  2210.  
  2211.      code > ( n1 n2 -- bool)
  2212.           Returns "true" if "n1" is greater than "n2"
  2213.  
  2214.      code ?within ( value lower upper -- bool)
  2215.           Tests if the parameter "value" is within the range "lower" to
  2216.           "upper". Returns "true" if within the range else "false".
  2217.  
  2218.      code u< ( u1 u2 -- bool)
  2219.           Returns "true" if "u1" is less than "u2".
  2220.  
  2221.      Numeric Conversion
  2222.  
  2223.      The Forth-83 Standard numeric conversion functions. The _t_i_l_e forth ker-
  2224.      nel extends the standard with string to number converter, and general
  2225.      number literal recognition.
  2226.  
  2227.      code # ( +d1 -- +d2 )
  2228.           The remainder of "+d1" divided by the value of "base" is converted
  2229.           to a ASCII character and appended to the output string toward lower
  2230.           memory addresses. "+d2" if the quotient and is maintained for
  2231.           further processing. Typically used between "<#" and "#>".
  2232.  
  2233.      code #> ( x -- addr +n)
  2234.           Pictured numeric output conversion is ended dropping "x".  "addr"
  2235.           is the address of the resulting output string.  "+n" is the number
  2236.           of characters in the output string.  "addr" and "+n" together are
  2237.           suitable for "type".
  2238.  
  2239.  
  2240.  
  2241.    34
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.    April 11, 1991                                                   FORTH(3X)
  2249.  
  2250.  
  2251.      code #s ( +x -- 0)
  2252.           "+x" is converted appending each resultant character into the pic-
  2253.           tured numeric output string until the quotient is zero. A single
  2254.           zero is appended to the output string if the number was initially
  2255.           zero. Typically used between "<#" and "#>".
  2256.  
  2257.      code <# ( x -- )
  2258.           Initialize pictured numeric output conversion. The words: "<# # #s
  2259.           hold sign #>" can be used to specify the conversion of a number
  2260.           into an ASCII text string stored in right-to-left order.
  2261.  
  2262.      code ?number ( str -- [n true] or [str false]) recognizer
  2263.           Convert a string of character to a number using the current "base".
  2264.           If the conversion is not possible the string is returned with a
  2265.           "false" flag indicating that the conversion failed otherwise the
  2266.           conversion value, the number, and a "true" flag is returned.
  2267.  
  2268.      variable base ( -- addr)
  2269.           The address of a variable containing the current numeric conversion
  2270.           radix.
  2271.  
  2272.      code binary ( -- )
  2273.           Set the input-output numeric conversion "base" to 2.
  2274.  
  2275.      code convert ( +d1 addr1 -- +d2 addr2)
  2276.           "+d2" is the result of converting the characters within the text
  2277.           beginning at "addr1"+1 into digits, using the value of "base", and
  2278.           accumulating each into "+d1" after multiplying "+d1" by the value
  2279.           of "base". Conversion continues until an inconvertible character is
  2280.           encountered. "addr2" is the location of the first inconvertible
  2281.           character.
  2282.  
  2283.      code decimal ( -- )
  2284.           Set the input-output numeric conversion "base" to 10.
  2285.  
  2286.      code hex ( -- )
  2287.           Set the input-output numeric conversion "base" to 16.
  2288.  
  2289.      code hold ( char -- )
  2290.           "char" is inserted into a pictured numeric output string.  Typi-
  2291.           cally used between "<#" and "#>".
  2292.  
  2293.      code octal ( -- )
  2294.           Set the input-output numeric conversion "base" to 8.
  2295.  
  2296.      code sign ( n -- )
  2297.           If "n" is negative, an ASCII "-" (minus sign) is appended to the
  2298.           pictured numerical output string. Typically used between "<#" and
  2299.           "#>".
  2300.  
  2301.      Control Structures
  2302.  
  2303.      The Forth-83 Standard control flow word set. The _t_i_l_e forth kernel
  2304.      extends the basic set of control structures with environment arguments
  2305.  
  2306.  
  2307.                                                                            35
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.    FORTH(3X)                                                   April 11, 1991
  2315.  
  2316.  
  2317.      access, conditional compilation, case structure, additional loop con-
  2318.      structs, and recursion words.
  2319.  
  2320.      code #else ( -- ) immediate
  2321.           Used in the following form:
  2322.           <_f_l_a_g> #if <_t_r_u_e-_p_a_r_t> #else <_e_l_s_e-_p_a_r_t> #then
  2323.           Marks the beginning of a "else"-part of a conditional code section.
  2324.  
  2325.      code #if ( flag -- ) immediate
  2326.           Used in the following form:
  2327.           <_f_l_a_g> #if <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then
  2328.           Marks the beginning of a conditional code section. The else section
  2329.           is optional.
  2330.  
  2331.      code #ifdef ( -- ) immediate
  2332.           Used in the following form for testing if a symbol already is
  2333.           available:
  2334.           #ifdef <_n_a_m_e> <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then
  2335.           If <_n_a_m_e> is available in the current search chain "context" the
  2336.           true section of code is executed or compiled according to mode else
  2337.           the optional false section.
  2338.  
  2339.      code #ifundef ( -- ) immediate
  2340.           Used in the following form:
  2341.           #ifundef <_n_a_m_e> <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then
  2342.           Performs the same function as "#ifdef" but the true section is exe-
  2343.           cuted if the symbol is not available in the current search chain.
  2344.  
  2345.      code #then ( -- ) immediate
  2346.           Used in the following form:
  2347.           <_f_l_a_g> #if <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then
  2348.           Marks the end of a conditional code section.
  2349.  
  2350.      code +loop ( n -- ) immediate compilation
  2351.           "n" is added to the loop index. If the new index was incremented
  2352.           across the boundary between limit-1 and limit then the loop is ter-
  2353.           minated and the loop control parameters are discarded. When the
  2354.           loop is not terminated, execution continues to just after the
  2355.           corresponding "do". "+loop" is not available outside a colon defin-
  2356.           ition.
  2357.  
  2358.      code ?do ( w1 w2 -- ) immediate compilation
  2359.           Used in the following forms:
  2360.           ?do ... { i | leave } ... loop
  2361.           or
  2362.           ?do ... { i | leave } ... +loop
  2363.           Begins a checked entry loop which terminates based on control
  2364.           parameters. The loop index begins at "w2", and terminates based on
  2365.           the limit "w1". See "loop" and "+loop" for details on how the loop
  2366.           is terminated. If "w1" and "w2" are equal the loop section is
  2367.           skipped.
  2368.  
  2369.      code abort ( -- )
  2370.           Clears the data stack and performs the function of "quit".  No
  2371.  
  2372.  
  2373.    36
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.    April 11, 1991                                                   FORTH(3X)
  2381.  
  2382.  
  2383.           message is displayed.
  2384.  
  2385.      code abort" ( flag -- ) immediate compilation
  2386.           Used in the following form:
  2387.           <_f_l_a_g> abort" <_a_b_o_r_t-_m_e_s_s_a_g_e> "
  2388.           When later executed, if "flag" is true the <_a_b_o_r_t-_m_e_s_s_a_g_e> delim-
  2389.           ited by close quote, is displayed and then a system dependent error
  2390.           abort sequence, including the function "abort", is performed. If
  2391.           "flag" is false, the flag is dropped and execution continues. The
  2392.           blank following abort" is not part of the <_a_b_o_r_t-_m_e_s_s_a_g_e>.
  2393.  
  2394.      code again ( -- ) immediate compilation
  2395.           Used in the following form to compile an eternal loop:
  2396.           begin ... again
  2397.           The loop construct may only be left by an "abort" or an "exit" word
  2398.           in the code section of the loop.
  2399.  
  2400.      code argc ( -- num)
  2401.           Returns the number of arguments passed from the environment.  The
  2402.           first argument is always the name of the application: "forth" or
  2403.           the name of the start symbol.
  2404.  
  2405.      code argv ( n -- str)
  2406.           Given an index returns the corresponding argument string. The
  2407.           "string" vocabulary words may be used for process an argument
  2408.           string.
  2409.  
  2410.      code begin ( -- ) immediate compilation
  2411.           Used in the following forms:
  2412.           begin ... <_f_l_a_g> while ... repeat
  2413.           or
  2414.           begin ... <_f_l_a_g> until
  2415.           or
  2416.           begin ... again
  2417.           "begin" marks the start of a word sequence for repetitive execu-
  2418.           tion. A "begin-while-repeat" loop will repeat until <_f_l_a_g> is
  2419.           false. "begin-until" loop will be repeated until <_f_l_a_g> is true and
  2420.           "begin-again" will repeat until "abort"-ed. The words after "until"
  2421.           and "repeat" will be executed when either loop is finished.
  2422.  
  2423.      code bye ( -- )
  2424.           Leaves the interaction level and exits to the outer support system
  2425.           (if any).
  2426.  
  2427.      code case ( value -- ) immediate compilation
  2428.           Used in the following form:
  2429.           case <_c_a_s_e-_s_t_r_u_c_t_u_r_e>  { <_d_e_f_a_u_l_t-_p_a_r_t> } endcase
  2430.           to mark the beginning of a case structure which should contain a
  2431.           one or several case statements:
  2432.           <_c_a_s_e-_v_a_l_u_e> of <_c_a_s_e-_p_a_r_t> endof
  2433.           The code section after the last case value part will receive
  2434.           "value" as a parameter thus a default behavior is easy implemented.
  2435.           The default section may only copy this value as "endcase" is an
  2436.           implicit "drop".
  2437.  
  2438.  
  2439.                                                                            37
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.    FORTH(3X)                                                   April 11, 1991
  2447.  
  2448.  
  2449.      code do ( w1 w2 -- )     immediate compilation
  2450.           Used in the following forms:
  2451.           do ... { i | leave } ... loop
  2452.           or
  2453.           do ... { i | leave } ... +loop
  2454.           Begins a loop which terminates based on control parameters.  The
  2455.           loop index begins at "w2", and terminates based on the limit "w1".
  2456.           See "loop" and "+loop" for details on how the loop is terminated.
  2457.           The loop is always executed at least once.
  2458.  
  2459.      code else ( -- ) immediate compilation
  2460.           Used in the following form:
  2461.           <_f_l_a_g> if <_t_r_u_e-_p_a_r_t> else <_f_a_l_s_e-_p_a_r_t> then
  2462.           in a conditional structure to mark the beginning of the false sec-
  2463.           tion. This section is executed when the <_f_l_a_g> is "false". The true
  2464.           section is then skipped.
  2465.  
  2466.      code endcase ( -- ) immediate compilation
  2467.           Used in the following form:
  2468.           case <_c_a_s_e-_s_t_r_u_c_t_u_r_e>  { <_d_e_f_a_u_l_t-_p_a_r_t> } endcase
  2469.           to mark the end of a case structure.
  2470.  
  2471.      code endof ( -- ) immediate compilation
  2472.           Used in the following form:
  2473.           <_c_a_s_e-_v_a_l_u_e> of <_c_a_s_e-_p_a_r_t> endof
  2474.           to mark the end of a cast value structure.
  2475.  
  2476.      code execute ( addr -- )
  2477.           The word definition indicated by "addr" is executed. An error con-
  2478.           dition exists if "addr" is not a compilation address.
  2479.  
  2480.      code exit ( -- ) compilation
  2481.           Compiled within a colon definition such that when executed, the
  2482.           colon definition returns control to the definition that passed con-
  2483.           trol to it by returning control to the return point on the top of
  2484.           the return stack. An error condition exists if the top of the
  2485.           return stack does not contain a valid return point. May not be used
  2486.           within a "do-loop" or "do-+loop" or an "exception"-block.
  2487.  
  2488.      code i ( -- w) compilation
  2489.           "w" is a copy of the current loop index. May only be used in the
  2490.           form:
  2491.           do ... { i | leave } ... loop
  2492.           or
  2493.           do ... { i | leave } ... +loop
  2494.           "i" is not visible outside a colon definition, i.e., when text
  2495.           interpreting and should only be used within a loop-block.
  2496.  
  2497.      code if ( flag -- ) immediate compilation
  2498.           Used in the following form:
  2499.           <_f_l_a_g> if <_t_r_u_e-_p_a_r_t> [ else <_e_l_s_e-_p_a_r_t> ] then
  2500.           If "flag" is true, the words following "if" are executed and the
  2501.           words following "else" until just after "then" are skipped. The
  2502.           "else" part is optional. If "flag" is false, words from "if"
  2503.  
  2504.  
  2505.    38
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.    April 11, 1991                                                   FORTH(3X)
  2513.  
  2514.  
  2515.           through "else", or from "if" through "then" (when no "else" is
  2516.           used) are skipped.
  2517.  
  2518.      code j ( -- w) compilation
  2519.           "w" is a copy of the index of the next outer loop. May only be used
  2520.           within a nested "do-loop" or "do-+loop" in the form:
  2521.           do ... do ... { i | j | leave } ... loop ... loop
  2522.           "j" is not visible outside a colon definition, i.e., when text
  2523.           interpreting.
  2524.  
  2525.      code leave ( -- ) compilation
  2526.           Transfers execution to just beyond the next "loop" or "+loop".  The
  2527.           loop is terminated and the loop control parameters are discarded.
  2528.           May only be used in the following forms:
  2529.           do ... { i | leave } ... loop
  2530.           or
  2531.           do ... { i | leave } ... +loop
  2532.           "leave" may appear within other control structures which are nested
  2533.           within the "do-loop" structure. More than one "leave" may appear
  2534.           within a do-loop.
  2535.  
  2536.      code loop ( -- ) immediate compilation
  2537.           Increments the "do-loop" index by one. If the new index was incre-
  2538.           mented across the boundary between limit-1 and limit the loop is
  2539.           terminated and the loop control parameters are discarded. When the
  2540.           loop is not terminated, execution continues to just after the
  2541.           corresponding "do".
  2542.  
  2543.      code of ( value -- ) immediate compilation
  2544.           Used in the following form:
  2545.           <_c_a_s_e-_v_a_l_u_e> of <_c_a_s_e-_p_a_r_t> endof
  2546.           within a case structure to define a value case.
  2547.  
  2548.      code quit ( -- )
  2549.           Clears the return stack, sets interpret state, accepts new input
  2550.           from the current input device, and begins text interpretation. No
  2551.           messages is displayed.
  2552.  
  2553.      code recurse ( -- ) immediate compilation
  2554.           Used within a definition to make a recursive call to the current
  2555.           definition.
  2556.  
  2557.      code repeat ( -- ) immediate compilation
  2558.           Used in the following form:
  2559.           begin ... <_f_l_a_g> while ... repeat
  2560.           At execution-time, "repeat" continues execution to just after the
  2561.           corresponding "begin".
  2562.  
  2563.      code tail-recurse ( -- ) immediate compilation
  2564.           Used within a definition to create a recursive call to the current
  2565.           definition without saving return status. This is an efficient way
  2566.           of generating iterative forms as tail recursive calls may be per-
  2567.           formed any number of times within a definition and corresponds to a
  2568.           branch to the beginning of the definition.
  2569.  
  2570.  
  2571.                                                                            39
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.    FORTH(3X)                                                   April 11, 1991
  2579.  
  2580.  
  2581.      code then ( -- ) immediate compilation
  2582.           Used in the following form:
  2583.           <_f_l_a_g> if <_t_r_u_e-_p_a_r_t> [ else <_e_l_s_e-_p_a_r_t> ] then
  2584.           Marks the end of a conditional statement "if-else-then".
  2585.  
  2586.      code until ( flag -- ) immediate compilation
  2587.           Used in the following form:
  2588.           begin ... <_f_l_a_g> until
  2589.           Marks the end of a "begin-until" loop which will terminate based on
  2590.           "flag". If "flag" is true, the loop is terminated.  If "flag" is
  2591.           false, execution continues to just after the corresponding "begin".
  2592.  
  2593.      code while ( flag -- ) immediate compilation
  2594.           Used in the following form:
  2595.           begin ... <_f_l_a_g> while ... repeat
  2596.           Selects conditional execution based on "flag". When "flag" is true,
  2597.           execution continues to just after the "while" through to the
  2598.           "repeat" which then continues execution to just after the "begin".
  2599.           When "flag" is false, execution continues to just after the
  2600.           "repeat", exiting the control structure.
  2601.  
  2602.      Terminal Input/Output
  2603.  
  2604.      The Forth-83 Standard terminal interaction functions. The _t_i_l_e forth
  2605.      kernel extends the basic set of input and output functions with field
  2606.      format output and access of the current input source file name and the
  2607.      current line number count.
  2608.  
  2609.      code . ( n -- )
  2610.           The absolute value of "n" is displayed in a free field format with
  2611.           a leading minus sign if "n" is negative. A space is emit after the
  2612.           number.
  2613.  
  2614.      code ." ( -- ) immediate compilation
  2615.           Used in the following form within a code definition:
  2616.           <_o_u_t_p_u_t-_s_t_r_i_n_g> "
  2617.           Later execution will display the characters <_o_u_t_p_u_t-_s_t_r_i_n_g> up to
  2618.           but but including the delimiter (close-quote). The blank following
  2619.           the "." " is not part of the <_o_u_t_p_u_t-_s_t_r_i_n_g> but the word separa-
  2620.           tor.
  2621.  
  2622.      code .( ( -- ) immediate
  2623.           Used in the following form:
  2624.           .( <_o_u_t_p_u_t-_c_o_m_m_e_n_t> )
  2625.           The characters <_o_u_t_p_u_t-_c_o_m_m_e_n_t> up to but not including the delim-
  2626.           iter (closing-parenthesis) are displayed. The blank following ".("
  2627.           is not part of the <_o_u_t_p_u_t-_c_o_m_m_e_n_t>.
  2628.  
  2629.      code .s ( -- )
  2630.           Displays the current parameter stack contents in the format:
  2631.           [ <depth> ] <bottom> \ ... \ <top>
  2632.  
  2633.      code ascii ( -- char) immediate
  2634.           Used in the following form:
  2635.  
  2636.  
  2637.    40
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.    April 11, 1991                                                   FORTH(3X)
  2645.  
  2646.  
  2647.           ascii <_c_h_a_r_a_c_t_e_r> ( -- char)
  2648.           to create a character literal.
  2649.  
  2650.      code cr ( -- )
  2651.           Emits ASCII characters carriage-return and line-feed.
  2652.  
  2653.      code emit ( x -- )
  2654.           The least-significant 7-bit ASCII character is displayed.
  2655.  
  2656.      code expect ( addr +n -- )
  2657.           Receive characters and store each into memory. The transfer begins
  2658.           at "addr" proceeding towards higher addresses one byte per charac-
  2659.           ter until either a "return" is received or until "+n" characters
  2660.           have been transferred. No more than "+n" characters will be stored.
  2661.           The "return" is not stored into memory. No characters are received
  2662.           or transferred if "+n" is zero. All characters actually received
  2663.           and stored into memory will be displayed, with "return" displaying
  2664.           as a space. The actual number of characters received is stored in
  2665.           the variable "span".
  2666.  
  2667.      code key ( -- x)
  2668.           The next extended ASCII character received. All valid ASCII charac-
  2669.           ters can be received. Control characters are not processed by the
  2670.           system for any editing purpose. Characters received by "key" are
  2671.           displayed in _t_i_l_e forth due to interaction with the operating sys-
  2672.           tem.
  2673.  
  2674.      code line ( -- +n)
  2675.           Returns the current number of lines received from the current input
  2676.           "source".
  2677.  
  2678.      code r. ( n w -- )
  2679.           The absolute value of "n" is displayed in a field format of width
  2680.           "w" with a leading minus sign if "n" is negative.
  2681.  
  2682.      code source ( -- str)
  2683.           Returns the name string of the fully path expanded current file
  2684.           name. "nil" is returned if the current source is the standard input
  2685.           device.
  2686.  
  2687.      code space ( -- )
  2688.           Displays an ASCII space, i.e., emits an ASCII space character code.
  2689.  
  2690.      code spaces ( +n -- )
  2691.           Displays "+n" ASCII spaces. Nothing is displayed if "+n" is zero.
  2692.  
  2693.      variable span ( -- addr)
  2694.           The address of a variable containing the count of characters actu-
  2695.           ally received and stored by the last execution of "expect".
  2696.  
  2697.      code type ( addr +n -- )
  2698.           "+n" characters are displayed from memory beginning with the char-
  2699.           acter at "addr" and continuing through consecutive addresses. Noth-
  2700.           ing is displayed if "+n" is zero.
  2701.  
  2702.  
  2703.                                                                            41
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.    FORTH(3X)                                                   April 11, 1991
  2711.  
  2712.  
  2713.      code u. ( u -- )
  2714.           "u" is displayed as an unsigned number in a free-field format.
  2715.  
  2716.      code u.r ( u w -- )
  2717.           "u" is displayed as an unsigned number in a field format with width
  2718.           "w".
  2719.  
  2720.      Interpreter
  2721.  
  2722.      The Forth-83 Standard interpreter functions. The _t_i_l_e forth kernel
  2723.      extends the interpreter word set with functions for loading of source
  2724.      files, library directory paths and mode marking of vocabulary entries.
  2725.      The additional modes allow marking with concern to the interpreter state
  2726.      and visibility across vocabularies.
  2727.  
  2728.      code #include ( -- )
  2729.           Used in the following form to load source files:
  2730.           #include <_f_i_l_e-_n_a_m_e>
  2731.           The <_f_i_l_e-_n_a_m_e> is any string until a white space character. The
  2732.           file is located using the current set of paths defined by the
  2733.           environment variables $TILEPATH, $PWD, and $HOME. If the file has
  2734.           already been included the operation is ignored.  The kernel main-
  2735.           tains a list of all loaded files with their fully expanded names.
  2736.  
  2737.      code #path ( -- )
  2738.           Used in the following form to define a file search path:
  2739.           #path <_p_a_t_h-_n_a_m_e>
  2740.           The input function, "#include", uses a set of path to allow shorter
  2741.           file names to be used and support source code libraries. The ini-
  2742.           tial set of paths are defined by the environment variables $PWD,
  2743.           $TILEPATH, and $HOME.
  2744.  
  2745.      code ( ( -- ) immediate
  2746.           Used in the following form:
  2747.           ( <_c_o_m_m_e_n_t-_s_t_r_i_n_g> )
  2748.           The characters enclosed by the delimiter ")" are considered com-
  2749.           ments. Comments are not otherwise processed. The blank following
  2750.           "(" is not part of the comment string. The number of characters in
  2751.           the comment string may be from zero to the number of characters
  2752.           remaining in the input stream up to the closing parenthesis.
  2753.  
  2754.      code , ( x -- )
  2755.           Allocates space for "x" then store value at "here cell -".
  2756.  
  2757.      code .name ( addr1 -- )
  2758.           Given the compilation address "addr1" of an entry prints the name
  2759.           of the entry.
  2760.  
  2761.      code >body ( addr1 -- addr2)
  2762.           "addr2" is the parameter field address corresponding to the compi-
  2763.           lation address "addr1".
  2764.  
  2765.      code ?compile ( -- ) compilation
  2766.           Used in the following form:
  2767.  
  2768.  
  2769.    42
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.    April 11, 1991                                                   FORTH(3X)
  2777.  
  2778.  
  2779.           ?compile <_c_o_m_p_i_l_e_d-_e_n_t_r_y>
  2780.           to compile an entry at run-time. Considers the compilation state at
  2781.           run-time. If the state is compiling then performs the same action
  2782.           as "compile" else does nothing and the succeeding word is executed
  2783.           and not compiled.
  2784.  
  2785.      code [ ( -- ) immediate
  2786.           Sets interpret (execution) state. The text from the input stream is
  2787.           subsequently interpreted. Typically usage see "literal".
  2788.  
  2789.      code [compile] ( -- ) immediate compilation
  2790.           Used in the following form:
  2791.           [compile] <_c_o_m_p_i_l_e_d-_e_n_t_r_y>
  2792.           Forces compilation of the succeeding word. This allows compilation
  2793.           of an "immediate" word when it would otherwise have been executed.
  2794.           If the entry is not found an error message is given.
  2795.  
  2796.      code \ ( -- ) immediate
  2797.           Used in the following form:
  2798.           \ <_c_o_m_m_e_n_t-_s_t_r_i_n_g>
  2799.           Comment terminate by end of line (carriage return).
  2800.  
  2801.      code ] ( -- )
  2802.           Sets compilation state. The text from the input stream is subse-
  2803.           quently compiled.
  2804.  
  2805.      code allot ( w -- )
  2806.           Allocated "w" bytes from the dictionary. The address to the next
  2807.           available dictionary location is updated accordingly.
  2808.  
  2809.      code align ( -- )
  2810.           Align dictionary pointer to nearest cell boundary.
  2811.  
  2812.      code cell ( -- bytes)
  2813.           Returns the number of bytes per cell. Four bytes for a 32-bit
  2814.           Forth.
  2815.  
  2816.      code cell+ ( n -- m)
  2817.           Returns the result, "m", of incrementing "n" by "cell".
  2818.  
  2819.      code cells ( n -- m)
  2820.           Returns the given value, "n", in cells. The result of "n" times
  2821.           "cell".
  2822.  
  2823.      code compilation ( -- )
  2824.           Used in the following form:
  2825.           : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; compilation
  2826.           Marks the most recently created dictionary entry as a word which is
  2827.           only available in compilation mode.
  2828.  
  2829.      code compile ( -- ) compilation
  2830.           Typically used in the following form:
  2831.           : <_n_a_m_e> ... compile <_c_o_m_p_i_l_e_d-_e_n_t_r_y> ... ; immediate compilation
  2832.           When <_n_a_m_e> is executed, the compilation address compiled for
  2833.  
  2834.  
  2835.                                                                            43
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.    FORTH(3X)                                                   April 11, 1991
  2843.  
  2844.  
  2845.           <_c_o_m_p_i_l_e_d-_e_n_t_r_y> is compiled and not executed.  <_n_a_m_e> is typically
  2846.           "immediate" and "compilation", and <_c_o_m_p_i_l_e_d-_e_n_t_r_y> is typically
  2847.           not an immediate word.
  2848.  
  2849.      code compiling ( -- bool)
  2850.           Returns the contents of the state variable as this variable should
  2851.           not be altered by other than system functions.
  2852.  
  2853.      code does> ( addr -- ) immediate compilation
  2854.           Defines the run-time action of a word created by a high-level
  2855.           defining word. Used in the following form:
  2856.           : <_d_e_f_i_n_i_n_g> ( ... )
  2857.           ... <_c_r_e_a_t_e-_d_e_f_i_n_i_t_i_o_n> ...
  2858.           does> ( addr -- ...)
  2859.           ... <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n> ... ;
  2860.           and then
  2861.           <defining> <_n_a_m_e> (...)
  2862.           where <_c_r_e_a_t_e-_d_e_f_i_n_i_t_i_o_n> is "create" or any user defined word
  2863.           which executes "create", and allocated memory. Marks the termina-
  2864.           tion of the defining part of the defining word <_d_e_f_i_n_i_n_g> and then
  2865.           begins the definition of the <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n> for words that
  2866.           will later be defined by <_d_e_f_i_n_i_n_g>. When <_n_a_m_e> is later executed,
  2867.           the parameter field address, "addr", of <_n_a_m_e> is pushed on the
  2868.           parameter stack and then the sequence of words between "does>" and
  2869.           ";", the <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n>, is executed. Multi-levels of high-
  2870.           level definitions are possible, i.e., "create-does>" may be used
  2871.           multiple times within the <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n>.
  2872.  
  2873.      code execution ( -- )
  2874.           Used in the following form:
  2875.           : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; execution
  2876.           Marks the most recently created dictionary entry as a word which is
  2877.           only available in execution mode.
  2878.  
  2879.      code here ( -- addr)
  2880.           The address of the next available dictionary location.
  2881.  
  2882.      constant dp ( -- addr)
  2883.           The address of the next available dictionary location pointer. Many
  2884.           be used to change the dictionary area.
  2885.  
  2886.      code immediate ( -- )
  2887.           Used in the following form:
  2888.           : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; immediate
  2889.           Marks the most recently created dictionary entry as a word which
  2890.           will be executed when encountered during compilation rather than
  2891.           compiled.
  2892.  
  2893.      code interpret ( -- )
  2894.           The forth top-loop; scan, locates, compiles and interprets symbols.
  2895.           The top-loop may be left with the word "bye".
  2896.  
  2897.      code literal ( n -- ) immediate compilation
  2898.           Typically used in the following form:
  2899.  
  2900.  
  2901.    44
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.    April 11, 1991                                                   FORTH(3X)
  2909.  
  2910.  
  2911.           [ <_e_x_p_r_e_s_s_i_o_n> ] literal
  2912.           At execution time "n" will be left on the parameter stack.
  2913.  
  2914.      create pad ( -- addr)
  2915.           The lower address of a scratch area used to hold data form inter-
  2916.           mediate processing. The address or contents of "pad" may change and
  2917.           the data lost if the address of the next available dictionary loca-
  2918.           tion is changed. The minimum capacity of "pad" is minimum of 84
  2919.           characters (bytes).
  2920.  
  2921.      code private ( -- )
  2922.           Used in the following form:
  2923.           : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; private
  2924.           Marks the most recently created dictionary entry as a word which is
  2925.           only available in the dictionary it is created in.  The word is not
  2926.           available when the dictionary is not the definitions vocabulary,
  2927.           "current".
  2928.  
  2929.      code quit ( -- )
  2930.           Clears the parameter stack and performs the function of "inter-
  2931.           pret".  Starts the forth interpreter and compiler.
  2932.  
  2933.      code recognizer ( -- )
  2934.           Used in the following form:
  2935.           : <_n_a_m_e> ( str -- [str false] or [x true]) ...  <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n>
  2936.           ... ; recognizer
  2937.           Marks the most recently created dictionary entry as a word which
  2938.           will perform the literal recognition function. Executed by "inter-
  2939.           pret" when an "entry" has not been found. The recognizer function
  2940.           for "forth" is "?number" and "?float" for "float".
  2941.  
  2942.      variable state ( -- addr)
  2943.           The address of a variable containing the compilation state.  True
  2944.           indicated compilation is occurring, false that text interpretation
  2945.           is occurring. A Standard Program may not modify this variable and
  2946.           should instead use "[" and "]" to alter mode.
  2947.  
  2948.      create tib ( -- addr)
  2949.           The address of the text input buffer. This buffer is used to hold
  2950.           characters when the input stream is coming from the current input
  2951.           device. The minimum capacity of "tib" is 256 characters.
  2952.  
  2953.      code word ( char -- addr)
  2954.           Generates a null-terminated string by non-destructively accepting
  2955.           characters from the input stream until the delimiter character code
  2956.           or a control character is encounter or the input stream is
  2957.           exhausted. Leading delimiters and control characters are ignored.
  2958.           The entire character string is stored in memory beginning at "addr"
  2959.           as a sequence of bytes.
  2960.  
  2961.      Vocabulary
  2962.  
  2963.      The Forth-83 standard vocabulary management functions. The _t_i_l_e forth
  2964.      kernel extends the basic function set with primitive entry lookup and
  2965.  
  2966.  
  2967.                                                                            45
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.    FORTH(3X)                                                   April 11, 1991
  2975.  
  2976.  
  2977.      literal recognition. Each vocabulary may have a literal recognition
  2978.      function which is automatically applied by "interpret" when the entry
  2979.      lookup fails. This allows easy extension of the input syntax for literal
  2980.      symbols. For examples see the "float" and the "rationals" vocabularies
  2981.      and files.
  2982.  
  2983.      code ' ( -- addr)
  2984.           Used in the form:
  2985.           ' <_n_a_m_e> ( -- addr)
  2986.           "addr" is the compilation address of <_n_a_m_e>. Gives an error message
  2987.           if <_n_a_m_e> is not found in the current active search order, "con-
  2988.           text".
  2989.  
  2990.      code ['] ( -- addr) immediate compilation
  2991.           Used in the form:
  2992.           ['] <_n_a_m_e> ( -- addr)
  2993.           Compiles the compilation address of <_n_a_m_e> as a literal. When the
  2994.           colon definition is later executed "addr" is left on the stack. If
  2995.           <_n_a_m_e> is not found an error message is given.
  2996.  
  2997.      set context ( -- addr)
  2998.           Variable containing the set of vocabularies in the search chain.
  2999.           The set is represented as a vector set in the _t_i_l_e forth kernel and
  3000.           may be manipulated with the functions from the "sets" extension.
  3001.  
  3002.      variable current ( -- addr)
  3003.           Variable containing a pointer to the current vocabulary for defini-
  3004.           tions.
  3005.  
  3006.      code definitions ( -- )
  3007.           The compilation vocabulary, "current", is changed to be the same as
  3008.           the first vocabulary in the search order, "context".
  3009.  
  3010.      code find ( addr1 -- addr2 n)
  3011.           "addr1" is the address of a null-ended string. The string contains
  3012.           a word name to located in the currently active search order. If the
  3013.           word is not found, "addr2" is the string and "n" is false. If the
  3014.           word is found, "addr2" is the compilation address and "n" is set to
  3015.           one of two non- zero values. If the word found has the immediate
  3016.           attribute set, "n" is one. If the word is non-immediate, n is minus
  3017.           one (true).
  3018.  
  3019.      code forget ( -- )
  3020.           Used in the form:
  3021.           forget <_n_a_m_e> ( -- )
  3022.           If <_n_a_m_e> is found in the compilation vocabulary, delete <_n_a_m_e>
  3023.           from the dictionary and all words added to the dictionary after
  3024.           <_n_a_m_e> regardless of their vocabulary. Failure to find <_n_a_m_e> is an
  3025.           error condition. An error condition also exists if the compilation
  3026.           vocabulary is deleted.
  3027.  
  3028.      vocabulary forth ( -- )
  3029.           The name of the primary vocabulary. Execution replaces the first
  3030.           vocabulary in the search order with "forth". "forth" is initially
  3031.  
  3032.  
  3033.    46
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.    April 11, 1991                                                   FORTH(3X)
  3041.  
  3042.  
  3043.           the compilation vocabulary and the first vocabulary in the search
  3044.           order. New definitions become part of the "forth" vocabulary until
  3045.           a different compilation vocabulary is established.
  3046.  
  3047.      code forth-83 ( -- )
  3048.           Assures that a Forth-83 Standard System is available.
  3049.  
  3050.      code last ( -- addr)
  3051.           Returns the compilation address of the latest defined entry in the
  3052.           current vocabulary.
  3053.  
  3054.      code lookup ( addr1 vocabulary -- addr2 n)
  3055.           "addr1" is the address of a null-ended string which is to be
  3056.           located in the "vocabulary" given as a parameter. If the word is
  3057.           not found, "addr2" is the string and "n" is false. If the word is
  3058.           found, "addr2" is the compilation address and "n" is set to one of
  3059.           two non-zero values. If the word found has the immediate attribute
  3060.           set, "n" is one. If the word is non-immediate, "n" is minus one.
  3061.  
  3062.      code only ( -- )
  3063.           The compilation vocabulary, "current", is changed to be the same as
  3064.           the first vocabulary in the search order, "context".  And all voca-
  3065.           bularies except the first is removed from the search list.
  3066.  
  3067.      code recognize ( addr1 -- [addr1 false] or [addr2 true])
  3068.           "addr1" is the address of a null-ended string. The string is tested
  3069.           by each recognizer function in the currently active search order.
  3070.           If recognized the function will return the literal value in "addr2"
  3071.           and "true". In other cases the string is returned with "false". The
  3072.           recognizer functions for the "forth" and "float" vocabularies are
  3073.           "?number" and "?float".
  3074.  
  3075.      code restore ( entry -- )
  3076.           Restores "current" to the parameter entry. Any words defined after
  3077.           "entry" are unlinked form the vocabulary. This is useful for real-
  3078.           izing lexical levels in forth. The lookup function cache is also
  3079.           flushed. An "nil" parameter will flush the whole cache.
  3080.  
  3081.      code seal ( -- )
  3082.           The first (top) vocabulary is removed from the set of search voca-
  3083.           bularies, "context". This allows lexical levels using vocabularies.
  3084.  
  3085.      code words ( -- ) immediate
  3086.           Display the visible words in the current search chain, "context".
  3087.  
  3088.      Defining Words
  3089.  
  3090.      The Forth-83 standard defining functions. The _t_i_l_e forth kernel extends
  3091.      the Forth-83 Standard with additional functions for creating vocabulary
  3092.      entries, fields, and forward declaration.
  3093.  
  3094.      code : ( -- )
  3095.           A defining word executed in the following form:
  3096.           : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ;
  3097.  
  3098.  
  3099.                                                                            47
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.    FORTH(3X)                                                   April 11, 1991
  3107.  
  3108.  
  3109.           Create a word definition for <_n_a_m_e> in the compilation vocabulary
  3110.           and set compilation state. The text from the input stream is subse-
  3111.           quently compiled.  <_n_a_m_e> is called a "colon definition".
  3112.  
  3113.      code ; ( -- ) immediate compilation
  3114.           Stops compilation of a colon definitions, sets interpret state.
  3115.           Additional actions may be taken for local variables and argument
  3116.           frames and an exception block.
  3117.  
  3118.      code code ( addr -- )
  3119.           Used in the following form:
  3120.           <_a_d_d_r> code <_n_a_m_e> ( ... )
  3121.           to create a kernel primitive which will execute code at the given
  3122.           address, "addr", when used. The "address" is assumed to be a
  3123.           pointer to a parameter-less procedure.
  3124.  
  3125.      code constant ( value -- )
  3126.           A defining word executed in the following form:
  3127.           <_v_a_l_u_e> constant <_n_a_m_e> ( -- value)
  3128.           Create a dictionary entry form <_n_a_m_e> so that when <_n_a_m_e> is later
  3129.           executed, <_v_a_l_u_e> will be left on the stack.
  3130.  
  3131.      code create ( -- )
  3132.           A defining word executed in the following form:
  3133.           create <_n_a_m_e> ( -- addr)
  3134.           Create a dictionary entry for <_n_a_m_e>. After <_n_a_m_e> is created, the
  3135.           next available dictionary location is the first byte of <_n_a_m_e>'_s
  3136.           parameter field. When <_n_a_m_e> is subsequently executed, the address
  3137.           of the first byte of <_n_a_m_e>'_s parameter field is left on the stack.
  3138.           "create" does not allocate space in <_n_a_m_e>'_s parameter field. The
  3139.           dictionary location is always aligned before the entry is created.
  3140.  
  3141.      code entry ( parameter mode code name -- )
  3142.           Creates a new entry in the current definitions vocabulary with the
  3143.           given arguments. The entry becomes the "last" entry in the vocabu-
  3144.           lary.
  3145.  
  3146.      code field ( offset -- )
  3147.           Used in the following form:
  3148.           <_o_f_f_s_e_t> field <_n_a_m_e> ( addr1 -- addr2)
  3149.           When later <_n_a_m_e> is used it will add the <_o_f_f_s_e_t> to the top of
  3150.           the parameter stack.
  3151.  
  3152.      code forward ( -- )
  3153.           Used in the following form to define a symbol which will be defined
  3154.           later:
  3155.           forward <_n_a_m_e> ( ... )
  3156.           If the symbol is executed it will indirectly execute "abort".  When
  3157.           the symbol is later defined the forwarded symbol is automatically
  3158.           redirected to the newly created symbol.
  3159.  
  3160.      code variable ( -- )
  3161.           A defining word executed in the following form:
  3162.           variable <_n_a_m_e> ( -- addr)
  3163.  
  3164.  
  3165.    48
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.    April 11, 1991                                                   FORTH(3X)
  3173.  
  3174.  
  3175.           A dictionary entry for <_n_a_m_e> is created and four bytes are allo-
  3176.           cated in its parameter field.  This parameter field is to be used
  3177.           for contents of the variable.  The application is responsible for
  3178.           initializing the contents of the variable which is created. When
  3179.           <_n_a_m_e> is later executed, the address of its parameter field is
  3180.           placed on the stack.
  3181.  
  3182.      code vocabulary ( -- )
  3183.           A defining word executed in the following form :
  3184.           vocabulary <_n_a_m_e> ( -- )
  3185.           A dictionary entry for <_n_a_m_e> is created which specifies a new
  3186.           ordered list of word definitions.  Subsequent execution of <_n_a_m_e>
  3187.           replaces the first vocabulary in the search order with <_n_a_m_e>. When
  3188.           <_n_a_m_e> becomes the compilation vocabulary new definitions will be
  3189.           appended to <_n_a_m_e>'_s list.
  3190.  
  3191.    INTERNALS
  3192.      For the internal data structures of the _t_i_l_e forth kernel see the source
  3193.      files "internals.f83" and the manual file "internals". The C definition
  3194.      of the data structures may be found in the file "kernel.h".
  3195.  
  3196.    SEE ALSO
  3197.      _t_i_l_e(_1), _m_e_m_o_r_y(_3_X), _c_o_m_p_i_l_e_r(_3_X), _l_o_c_a_l_s(_3_X), _e_x_c_e_p_t_i_o_n_s(_3_X),
  3198.      _f_l_o_a_t(_3_X), _s_t_r_i_n_g(_3_X), _q_u_e_u_e_s(_3_X), _m_u_l_t_i-_t_a_s_k_i_n_g(_3_X).
  3199.  
  3200.    NOTE
  3201.      The function lists are sorted in ASCII order. The type and mode of the
  3202.      entries are indicated together with their parameter stack effect.
  3203.  
  3204.    COPYING
  3205.      Copyright (C) 1990 Mikael R.K. Patel
  3206.  
  3207.      Permission is granted to make and distribute verbatim copies of this
  3208.      manual provided the copyright notice and this permission notice are
  3209.      preserved on all copies.
  3210.  
  3211.      Permission is granted to copy and distribute modified versions of this
  3212.      manual under the conditions for verbatim copying, provided also that the
  3213.      section entitled "GNU General Public License" is included exactly as in
  3214.      the original, and provided that the entire resulting derived work is
  3215.      distributed under the terms of a permission notice identical to this
  3216.      one.
  3217.  
  3218.      Permission is granted to copy and distribute translations of this manual
  3219.      into another language, under the above conditions for modified versions,
  3220.      except that the section entitled "GNU General Public License" may be
  3221.      included in a translation approved by the author instead of in the ori-
  3222.      ginal English.
  3223.  
  3224.    AUTHOR
  3225.      Mikael R.K. Patel
  3226.      Computer Aided Design Laboratory (CADLAB)
  3227.      Department of Computer and Information Science
  3228.      Linkoping University
  3229.  
  3230.  
  3231.                                                                            49
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.    FORTH(3X)                                                   April 11, 1991
  3239.  
  3240.  
  3241.      S-581 83 LINKOPING
  3242.      SWEDEN
  3243.  
  3244.      Email: mip@ida.liu.se
  3245.  
  3246.  
  3247.  
  3248.  
  3249.  
  3250.  
  3251.  
  3252.  
  3253.  
  3254.  
  3255.  
  3256.  
  3257.  
  3258.  
  3259.  
  3260.  
  3261.  
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.    50
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.    August 1, 1990                                               INTERNALS(3X)
  3305.  
  3306.  
  3307.  
  3308.    NAME
  3309.      internals - tile forth kernel internal data structures
  3310.  
  3311.    SYNOPSIS
  3312.      #include internals.f83
  3313.  
  3314.      forth
  3315.  
  3316.    DESCRIPTION
  3317.      High level definitions of the internal data structures of the _t_i_l_e forth
  3318.      kernel.  Defines the structure of vocabulary entries; the linkage struc-
  3319.      ture, name string, mode field, interpretation code, and parameter field.
  3320.      Utility functions for displaying the current vocabulary search order,
  3321.      the current definitions vocabulary and the internal state of an entry.
  3322.      General definitions iterator for extraction of entries of specific code
  3323.      type.
  3324.  
  3325.      Numerical constants
  3326.  
  3327.      Predefined constants for some of the most common values used for storage
  3328.      allocation and integer value initialization.
  3329.  
  3330.      constant BITS/BYTE ( -- num)
  3331.           Number of bits per byte.
  3332.  
  3333.      constant BITS/WORD ( -- num)
  3334.           Number of bits per word in stack data etc.
  3335.  
  3336.      constant BYTES/WORD ( -- num)
  3337.           Number of bytes per word.
  3338.  
  3339.      constant MAX_INT ( -- int)
  3340.           Maximum integer number in two's complement.
  3341.  
  3342.      constant MIN_INT ( -- int)
  3343.           Minimum integer number in two's complement.
  3344.  
  3345.      Entry structure
  3346.  
  3347.      The internal fields of an entry in a _t_i_l_e forth vocabulary. Defined as a
  3348.      structure with the traditional fields; link, name, mode, code, and
  3349.      parameter. Definition of the entry mode and interpretation code field.
  3350.  
  3351.      struct.type ENTRY ( -- )
  3352.           Structure of vocabulary entries. Contains the fields; "+link",
  3353.           "+name", "+mode", "+code", and "+parameter".
  3354.  
  3355.      ptr +link ( entry -- addr)
  3356.           Field access of link to predecessor entry in vocabulary list. The
  3357.           vocabulary chain is maintained as a linked list in definition order
  3358.           and may be manipulated with the "lists" extensions.
  3359.  
  3360.      ptr +name ( entry -- addr)
  3361.  
  3362.  
  3363.                                                                            51
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.    INTERNALS(3X)                                               August 1, 1990
  3371.  
  3372.  
  3373.           Field access of name string of an entry. The string is stored as a
  3374.           null terminated character sequence and may be manipulated using the
  3375.           "string" extensions.
  3376.  
  3377.      long +mode ( entry -- addr)
  3378.           Field access of mode bit field of an entry. See also "ENTRY-MODES"
  3379.           for the definition of the bit fields.
  3380.  
  3381.      long +code ( entry -- addr)
  3382.           Field access of code enumerative of an entry. Stored as a number,
  3383.           enum, or pointer to high level code. See also "ENTRY-CODES".  If
  3384.           the code field contains a number larger than the exception entry
  3385.           code "EXCEPTION" it is interpreted as a pointer to a high level
  3386.           management block by the inner address interpreter.
  3387.  
  3388.      long +parameter ( entry -- addr)
  3389.           Field access of parameter part of entry structure. Stored as a
  3390.           long. May contain a pointer to the body of the entry. This is the
  3391.           case for colon definitions and other entries with bodies larger
  3392.           than a "cell". The kernel word ">body" returns the contents of this
  3393.           field.
  3394.  
  3395.      bitfield.type ENTRY-MODES ( -- )
  3396.           Bit field structure definition of the possible set of entry modes.
  3397.           The kernel uses four bits and allows applications to use the bits
  3398.           within the three most significant bytes (bit 8-31).  Defines the
  3399.           modes "IMMEDIATE", "EXECUTION", "COMPILATION", and "PRIVATE" as bit
  3400.           fields. These may be manipulated with the "bitfields" extension.
  3401.  
  3402.      bit IMMEDIATE ( -- pos width)
  3403.           Access of immediate bit field in the mode field of an entry. If the
  3404.           bit is set the entry is an "immediate" word. This bit is set by the
  3405.           kernel word "immediate".
  3406.  
  3407.      bit EXECUTION ( -- pos width)
  3408.           Access of execution bit field in mode. If the bit is set the entry
  3409.           is not visible in compilation mode. This bit may be set by the ker-
  3410.           nel word "execution".
  3411.  
  3412.      bit COMPILATION ( -- pos width)
  3413.           Access of compilation bit field in mode. If the bit is set the
  3414.           entry is not visible in execution mode. This bit may be set by the
  3415.           kernel word "compilation"
  3416.  
  3417.      bit PRIVATE ( -- pos width)
  3418.           Access of private bit field in mode. If the bit is set the entry is
  3419.           only visible when the vocabulary in which it is defined is
  3420.           currently the definitions, "current", vocabulary.
  3421.  
  3422.      bits RESERVED ( -- pos width)
  3423.           Access of reserved bit field in mode. These bits of the mode are
  3424.           reserved for the kernel. Bits 8-31 may be freely used by applica-
  3425.           tions.
  3426.  
  3427.  
  3428.  
  3429.    52
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.    August 1, 1990                                               INTERNALS(3X)
  3437.  
  3438.  
  3439.      enum.type ENTRY-CODES ( -- )
  3440.           Predefined code types. Used by the kernel, inner interpreter, to
  3441.           determine management of primitives. Defines the enumerates; "CODE",
  3442.           "COLON", "VARIABLE", "CONSTANT", "VOCABULARY", "CREATE", "USER",
  3443.           "LOCAL", and "EXCEPTION". Codes larger than "EXCEPTION" are
  3444.           regarded as pointers to forth level management code, and are used
  3445.           to implement high level management compiled by the words following
  3446.           "does>".
  3447.  
  3448.      enum CODE ( -- enum)
  3449.           Numeral for machine level code management. The parameter field of
  3450.           the entry is a pointer to a C procedure implementing the function.
  3451.           The inner interpreter will call the procedure.
  3452.  
  3453.      enum COLON ( -- enum)
  3454.           Numeral for forth level code management. The parameter field of the
  3455.           entry is a pointer to the body of the definition. The inner inter-
  3456.           preter will push the instruction pointer onto the return stack and
  3457.           use the parameter field as the new instruction pointer.
  3458.  
  3459.      enum VARIABLE ( -- enum)
  3460.           Numeral to mark variable management of entry. The parameter field
  3461.           of the entry is used for the variable area. The address of the
  3462.           parameter field is pushed onto the data stack.
  3463.  
  3464.      enum CONSTANT ( -- enum)
  3465.           Numeral to mark constant management of entry. The parameter field
  3466.           contains the constant value. The value is pushed onto the data
  3467.           stack.
  3468.  
  3469.      enum VOCABULARY ( -- enum)
  3470.           Numeral to mark vocabulary management of entry. The parameter field
  3471.           contains a pointer to the latest defined entry in the vocabulary.
  3472.           The vocabulary is appended first to the vocabulary search set,
  3473.           "context".
  3474.  
  3475.      enum CREATE ( -- enum)
  3476.           Numeral to mark create, symbol, management of entry. The parameter
  3477.           field contains a pointer to the data area for the entry.  This
  3478.           pointer is pushed onto the parameter stack by the inner inter-
  3479.           preter.
  3480.  
  3481.      enum USER ( -- enum)
  3482.           Numeral to mark user management of entry. The parameter field con-
  3483.           tains the offset from the task instance pointer.  The address of
  3484.           the user variable, calculated from the current running task
  3485.           pointer, "running", and the offset is pushed onto the parameter
  3486.           stack by the inner interpreter.
  3487.  
  3488.      enum LOCAL ( -- enum)
  3489.           Numeral to mark local variable management of entry. The parameter
  3490.           field contains the offset within the current frame to the location
  3491.           of the argument or local variable.  The value of the frame variable
  3492.           is pushed onto the parameter stack.
  3493.  
  3494.  
  3495.                                                                            53
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.    INTERNALS(3X)                                               August 1, 1990
  3503.  
  3504.  
  3505.      enum FORWARD ( -- enum)
  3506.           Numeral to mark forward management of entry. The parameter field
  3507.           contains initially "nil" and is replaced if the entry is redefined
  3508.           later. If the entry is used before defined an error message is
  3509.           given and execution is aborted.
  3510.  
  3511.      enum FIELD ( -- enum)
  3512.           Numeral to mark field management of entry. The parameter field con-
  3513.           tains the field offset. The offset is added to the pointer on top
  3514.           of the parameter stack.
  3515.  
  3516.      enum EXCEPTION ( -- enum)
  3517.           Numeral to mark exception variable management of entry. The parame-
  3518.           ter field contains a pointer to the entry.
  3519.  
  3520.      Utility functions
  3521.  
  3522.      Functions for displaying the current vocabulary search path and internal
  3523.      state of entries. Also display function to retrieve the current set of
  3524.      vocabularies.
  3525.  
  3526.      : .entry ( entry -- )
  3527.           Given a pointer to an entry prints all fields of the entry.
  3528.  
  3529.      : .context ( -- )
  3530.           Similar to "words" but prints the current state of the vocabulary
  3531.           search set, "context".
  3532.  
  3533.      : .current ( -- )
  3534.           Prints the name of the current definitions vocabulary.
  3535.  
  3536.      : .entries ( code -- )
  3537.           Prints the name of the available entries of the given code type
  3538.           along the current definitions vocabulary, "current".
  3539.  
  3540.    SEE ALSO
  3541.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_i_n_g(_3_X), _e_n_u_m_e_r_a_t_e_s(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X),
  3542.      _b_i_t_f_i_e_l_d_s(_3_X), _b_l_o_c_k_s(_3_X), _l_i_s_t_s(_3_X), _s_e_t_s(_3_X).
  3543.  
  3544.    EXAMPLES
  3545.      To print the internal fields of the entry _f_o_r_t_h, and access and verify
  3546.      its code type:
  3547.  
  3548.           #include internals.f83
  3549.  
  3550.      A procedure to print out all variables in the "current" vocabulary:
  3551.  
  3552.           #include blocks.f83
  3553.           #include lists.f83
  3554.  
  3555.           blocks lists
  3556.  
  3557.           : .variables ( -- )
  3558.                last
  3559.  
  3560.  
  3561.    54
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.    August 1, 1990                                               INTERNALS(3X)
  3569.  
  3570.  
  3571.                block[ ( entry -- )
  3572.                     dup +code @ VARIABLE =
  3573.                     if .name space else drop then
  3574.                ];
  3575.                map-list
  3576.           ;
  3577.  
  3578.    NOTE
  3579.      The function list in each sub-section is sorted in logical order. The
  3580.      type and mode of the entries are indicated together with their parameter
  3581.      stack effect.
  3582.  
  3583.    WARNING
  3584.      These extensions are very implementation dependent and caution must be
  3585.      take as code written using these definitions is not directly portable to
  3586.      other forth environments.
  3587.  
  3588.    COPYING
  3589.      Copyright (C) 1990 Mikael R.K. Patel
  3590.  
  3591.      Permission is granted to make and distribute verbatim copies of this
  3592.      manual provided the copyright notice and this permission notice are
  3593.      preserved on all copies.
  3594.  
  3595.      Permission is granted to copy and distribute modified versions of this
  3596.      manual under the conditions for verbatim copying, provided also that the
  3597.      section entitled "GNU General Public License" is included exactly as in
  3598.      the original, and provided that the entire resulting derived work is
  3599.      distributed under the terms of a permission notice identical to this
  3600.      one.
  3601.  
  3602.      Permission is granted to copy and distribute translations of this manual
  3603.      into another language, under the above conditions for modified versions,
  3604.      except that the section entitled "GNU General Public License" may be
  3605.      included in a translation approved by the author instead of in the ori-
  3606.      ginal English.
  3607.  
  3608.    AUTHOR
  3609.      Mikael R.K. Patel
  3610.      Computer Aided Design Laboratory (CADLAB)
  3611.      Department of Computer and Information Science
  3612.      Linkoping University
  3613.      S-581 83 LINKOPING
  3614.      SWEDEN
  3615.      Email: mip@ida.liu.se
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.                                                                            55
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.    IO(3X)                                                      April 11, 1991
  3635.  
  3636.  
  3637.  
  3638.    NAME
  3639.      io - tile kernel unix standard io interface
  3640.  
  3641.    SYNOPSIS
  3642.      io
  3643.  
  3644.    DESCRIPTION
  3645.      The _t_i_l_e forth kernel support word set for the standard unix system
  3646.      calls and library for io.
  3647.  
  3648.      vocabulary io ( -- )
  3649.           The Unix standard library io functions. The io vocabulary is an
  3650.           non-standard extension of Forth-83 and not directly portable to
  3651.           other forth environments.
  3652.  
  3653.      code open ( filename flags mode -- des)
  3654.           Opens a named file for reading and/or writing, as specified by the
  3655.           flags argument. The parameter is used when a new file is created to
  3656.           define the access mode of the file. Return a file descriptor or
  3657.           error.
  3658.  
  3659.      code close ( des -- int)
  3660.           Closes the file associated with the descriptor. Returns the value 0
  3661.           is successful else the value -1 is returned to indicate an error.
  3662.  
  3663.      code read ( des buf nbytes -- int)
  3664.           Attempts to read nbytes of data from the file references by the
  3665.           descriptor into the buffer pointed to by buf. Returns the number of
  3666.           bytes actually read. If EOF the return is 0.
  3667.  
  3668.      code write ( des buf nbytes -- int)
  3669.           Attempts to write nbytes of data from the buffer pointer to by buf
  3670.           to the file referenced by the descriptor. Returns the number of
  3671.           bytes actually written otherwise the return value -1 to indicate an
  3672.           error.
  3673.  
  3674.      code lseek ( des offset whence -- int)
  3675.           Positions the file referenced by the descriptor to the position
  3676.           given by the offset and the position mode whence. The modes are
  3677.           absolute (0), relative (1), and relative end of file (2). Returns
  3678.           the new position on the file in bytes else the value -1 to indicate
  3679.           an error.
  3680.  
  3681.      code fdopen ( des type -- stream)
  3682.           Associates a stream with the file descriptor des.
  3683.  
  3684.      code fopen ( filename type -- stream)
  3685.           Opens the file named by filename and associates a stream with it.
  3686.           If the open is successful the word return a pointer to the the
  3687.           stream else NIL is returned. The type parameter is a string with
  3688.           one of the following values: "r" for read, "w" for write, "a" for
  3689.           append, "r+" for update, "w+" for truncate or create for update,
  3690.           and "a+" open or create for update for EOF.
  3691.  
  3692.  
  3693.    56
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.    April 11, 1991                                                      IO(3X)
  3701.  
  3702.  
  3703.      code fclose ( stream -- int)
  3704.           Writes out any buffered data and closes the stream. Internal
  3705.           buffers are freed. Returns 0 if successful else the value EOF is
  3706.           returned.
  3707.  
  3708.      code fgetc ( stream -- int)
  3709.           Reads a character for the stream. Returns EOF at EOF or at an
  3710.           error.
  3711.  
  3712.      code fgets ( stream buf nbytes -- buf)
  3713.           Reads a sequence of characters from the stream into the buffer buf
  3714.           until EOF or NEWLINE or nbytes-1 have been received. The input
  3715.           string is null terminated.
  3716.  
  3717.      code fputc ( stream char -- int)
  3718.           Writes a character to the stream. Returns the character written.
  3719.  
  3720.      code fputs ( stream buf -- int)
  3721.           Writes the null terminated string to the stream. Returns EOF on
  3722.           error.
  3723.  
  3724.      code ungetc ( stream char -- int)
  3725.           Puts back a character on the stream.
  3726.  
  3727.      code ftell ( stream -- int)
  3728.           Return current position on stream.
  3729.  
  3730.      fseek ( stream position -- int)
  3731.           Move stream pointer to a new position.
  3732.  
  3733.      fflush ( stream -- int)
  3734.           Flush buffered data on the stream.
  3735.  
  3736.    SEE ALSO
  3737.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  3738.  
  3739.    NOTE
  3740.      The function list is sorted in logical order. The type and mode of the
  3741.      entries are indicated together with their parameter stack effect.
  3742.  
  3743.    COPYING
  3744.      Copyright (C) 1991 Mikael R.K. Patel
  3745.  
  3746.      Permission is granted to make and distribute verbatim copies of this
  3747.      manual provided the copyright notice and this permission notice are
  3748.      preserved on all copies.
  3749.  
  3750.      Permission is granted to copy and distribute modified versions of this
  3751.      manual under the conditions for verbatim copying, provided also that the
  3752.      section entitled "GNU General Public License" is included exactly as in
  3753.      the original, and provided that the entire resulting derived work is
  3754.      distributed under the terms of a permission notice identical to this
  3755.      one.
  3756.  
  3757.  
  3758.  
  3759.                                                                            57
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.    IO(3X)                                                      April 11, 1991
  3767.  
  3768.  
  3769.      Permission is granted to copy and distribute translations of this manual
  3770.      into another language, under the above conditions for modified versions,
  3771.      except that the section entitled "GNU General Public License" may be
  3772.      included in a translation approved by the author instead of in the ori-
  3773.      ginal English.
  3774.  
  3775.    AUTHOR
  3776.      Mikael R.K. Patel
  3777.      Computer Aided Design Laboratory (CADLAB)
  3778.      Department of Computer and Information Science
  3779.      Linkoping University
  3780.      S-581 83 LINKOPING
  3781.      SWEDEN
  3782.  
  3783.      Email: mip@ida.liu.se
  3784.  
  3785.  
  3786.  
  3787.  
  3788.  
  3789.  
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.    58
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.    August 6, 1990                                                   LISTS(3X)
  3833.  
  3834.  
  3835.  
  3836.    NAME
  3837.      lists - single linked lists definitions
  3838.  
  3839.    SYNOPSIS
  3840.      #include lists.f83
  3841.  
  3842.      lists
  3843.  
  3844.    DESCRIPTION
  3845.      This library supports definition and manipulation of single linked
  3846.      lists.  The list is assumed to have a pointer field first in each ele-
  3847.      ment.  The pointer gives access to the next element in the list. The
  3848.      list is terminated by "nil". The _t_i_l_e forth kernel vocabulary chain is
  3849.      realized as a single linked lists of entries.
  3850.  
  3851.      : ?empty-list ( list -- bool)
  3852.           Returns "true" if the list is empty else "false".
  3853.  
  3854.      : ?map-list ( list block[element -- bool] -- )
  3855.           List conditional iterator function. The code block is called for
  3856.           each element of the list while the block returns "false".
  3857.  
  3858.      : ?member-list ( element list -- bool)
  3859.           Returns "true" if the element is a member of the list else "false".
  3860.  
  3861.      : append-list ( element list -- )
  3862.           Appends the element last in the list. The list is searched first so
  3863.           that the element is not a member of the list. In this case no
  3864.           operation is performed.
  3865.  
  3866.      : apply-list ( offset list -- )
  3867.           List iteration function accessing each element of the list at the
  3868.           given offset as a pointer field and executing the field as an
  3869.           entry.
  3870.  
  3871.      : empty-list ( list -- )
  3872.           Assigns a list to become the empty list. The list will point to
  3873.           "nil".
  3874.  
  3875.      : insert-list ( element list -- )
  3876.           Inserts the element into the list. If the list a list element the
  3877.           parameter element is inserted after.
  3878.  
  3879.      : list ( -- )
  3880.           Used in the following form:
  3881.           list <_l_i_s_t-_n_a_m_e> ( -- addr)
  3882.           to create a list header. The header is initiated to "nil".
  3883.  
  3884.      : map-list ( list block[element -- ] -- )
  3885.           List iterator function. The code block is called for each element
  3886.           of the list.
  3887.  
  3888.      vocabulary lists ( -- )
  3889.  
  3890.  
  3891.                                                                            59
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.    LISTS(3X)                                                   August 6, 1990
  3899.  
  3900.  
  3901.           The single linked list extension vocabulary. Include into the voca-
  3902.           bulary search set, "context", to allow access to these functions.
  3903.  
  3904.      : size-list ( list -- num)
  3905.           Returns the size of the list, i.e., the number of element in the
  3906.           list.
  3907.  
  3908.    INTERNALS
  3909.      The _l_i_s_t_s vocabulary contains the following private definition to search
  3910.      lists of append and check membership.
  3911.  
  3912.      : search-list ( element list -- [element last] or [false]) private
  3913.           Searches through the list after the element. If not found returns
  3914.           the searched and the last element so that the element may be
  3915.           inserted.  If found returns "false".
  3916.  
  3917.    SEE ALSO
  3918.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _b_l_o_c_k_s(_3_X).
  3919.  
  3920.    EXAMPLES
  3921.      The internal definition of a vocabulary entry in the _t_i_l_e forth kernel
  3922.      has the following structure. The entry list may be manipulated with the
  3923.      "lists" extensions.
  3924.  
  3925.           #include structures.f83
  3926.           #include lists.f83
  3927.           #include blocks.f83
  3928.  
  3929.           structures lists blocks
  3930.  
  3931.           struct.type ENTRY ( -- )
  3932.                ptr  +link ( entry -- addr)
  3933.                ptr  +name ( entry -- addr)
  3934.                long +mode ( entry -- addr)
  3935.                long +code ( entry -- addr)
  3936.                long +parameter ( entry -- addr)
  3937.           struct.end
  3938.  
  3939.           last block[ ( entry -- ) . ]; map-list
  3940.  
  3941.    NOTE
  3942.      The function list is sorted in ASCII order. The type and mode of the
  3943.      entry is indicated together with the parameter stack effect.
  3944.  
  3945.    COPYING
  3946.      Copyright (C) 1990 Mikael R.K. Patel
  3947.  
  3948.      Permission is granted to make and distribute verbatim copies of this
  3949.      manual provided the copyright notice and this permission notice are
  3950.      preserved on all copies.
  3951.  
  3952.      Permission is granted to copy and distribute modified versions of this
  3953.      manual under the conditions for verbatim copying, provided also that the
  3954.      section entitled "GNU General Public License" is included exactly as in
  3955.  
  3956.  
  3957.    60
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.    August 6, 1990                                                   LISTS(3X)
  3965.  
  3966.  
  3967.      the original, and provided that the entire resulting derived work is
  3968.      distributed under the terms of a permission notice identical to this
  3969.      one.
  3970.  
  3971.      Permission is granted to copy and distribute translations of this manual
  3972.      into another language, under the above conditions for modified versions,
  3973.      except that the section entitled "GNU General Public License" may be
  3974.      included in a translation approved by the author instead of in the ori-
  3975.      ginal English.
  3976.  
  3977.    AUTHOR
  3978.      Mikael R.K. Patel
  3979.      Computer Aided Design Laboratory (CADLAB)
  3980.      Department of Computer and Information Science
  3981.      Linkoping University
  3982.      S-581 83 LINKOPING
  3983.      SWEDEN
  3984.      Email: mip@ida.liu.se
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.                                                                            61
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.    LOCALS(3X)                                                  August 1, 1990
  4031.  
  4032.  
  4033.  
  4034.    NAME
  4035.      locals - tile kernel argument binding and local variable functions
  4036.  
  4037.    SYNOPSIS
  4038.      locals
  4039.  
  4040.    DESCRIPTION
  4041.      The _t_i_l_e kernel support for argument binding and local variables in
  4042.      colon definitions. The _t_i_l_e forth virtual machine model support building
  4043.      and disposing of argument frames. The frame is build directly on the
  4044.      parameter stack. This minimizes the amount of data that has to be moved.
  4045.      Arguments and local variables are accessed by a frame pointer.  The
  4046.      frame pointer is automatically maintained by the virtual machine. On the
  4047.      exit of a colon definition using "locals" the frame is disposed and
  4048.      return values moved to their correct position on the parameter stack.
  4049.      Other forth implementation build the frame on a separate stack or on the
  4050.      return stack.  This implementation is much more efficient when the
  4051.      number of return values is often less than the number of arguments and
  4052.      local variables.
  4053.  
  4054.      code -> ( x -- ) compilation
  4055.           Assigns an argument or local variable with the value "x". Used in
  4056.           the following form:
  4057.           <_v_a_l_u_e> -> <_f_r_a_m_e-_v_a_r_i_a_b_l_e>
  4058.           The word after the assignment operator must be a <_f_r_a_m_e-_v_a_r_i_a_b_l_e>
  4059.           otherwise an error is accounted. The compiler does not check this
  4060.           error situation.
  4061.  
  4062.      code exit ( -- ) compilation
  4063.           Performs the equivalent action of the normal "exit" but also
  4064.           restores the stack after argument binding and local variables.
  4065.  
  4066.      vocabulary locals ( -- )
  4067.           Vocabulary containing the argument binding and local variable
  4068.           extension. Include into the vocabulary search structure, "context",
  4069.           to allow access to these extensions.
  4070.  
  4071.      code { ( -- ) immediate compilation
  4072.           Starts the named argument and local variable compiler. Used in the
  4073.           following forms:
  4074.           { <_a_r_g_u_m_e_n_t-_n_a_m_e_s> | <_l_o_c_a_l-_n_a_m_e_s> -- <_a_n_y> }
  4075.           or
  4076.           { <_a_r_g_u_m_e_n_t-_n_a_m_e_s> -- <_a_n_y> }
  4077.           or
  4078.           { | <_l_o_c_a_l-_n_a_m_e_s> -- <_a_n_y> }
  4079.           The different parts are as shown optional. The only restriction is
  4080.           that the definition of argument and local variable names is ter-
  4081.           minated by "}" or "--". In the "--" case characters until "}" are
  4082.           skipped and may be regarded as a comment. Return values are not
  4083.           named.
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.    62
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.    August 1, 1990                                                  LOCALS(3X)
  4097.  
  4098.  
  4099.    INTERNALS
  4100.      The following set of functions are mainly used to implement the argument
  4101.      binding and local variable frame management.
  4102.  
  4103.      code (link) ( arguments -- frame old-frame-pointer) compilation
  4104.           Compiled by "{" to perform the run-time action of building the
  4105.           argument and local variable frame. The frame is built directly on
  4106.           the parameter stack to minimize data movement. The frame consists
  4107.           of the arguments and stack area for the local variables. The old
  4108.           frame pointer is stored on the top of the parameter stack, making
  4109.           lexical levels possible. A pointer to the top of the frame, i.e.,
  4110.           the parameter stack top, is saved on the return stack so that
  4111.           return values may be moved down to their correct position on the
  4112.           parameter stack and the old frame pointer restored. The frame
  4113.           pointer will point to the first element below the first argument.
  4114.           This element will become the top of stack if no values are
  4115.           returned.
  4116.  
  4117.      code (local) ( -- addr) compilation
  4118.           Returns the address of an argument or local variable within the
  4119.           current frame using an inline literal offset. To access the address
  4120.           of the first variable in the frame the offset should be one.
  4121.  
  4122.      code (local!) ( value -- ) compilation
  4123.           Stores "value" to an argument or local variable within the current
  4124.           argument frame using an inline literal offset. To assign the first
  4125.           variable in the frame the offset should be one.
  4126.  
  4127.      code (local@) ( -- value) compilation
  4128.           Access the value of an argument or local variable within the
  4129.           current argument frame using an inline literal offset. To access
  4130.           the value of the first variable in the frame the offset should be
  4131.           one.
  4132.  
  4133.      code (unlink) ( frame return -- return) compilation
  4134.           Drops the frame and move the return values down. The old frame
  4135.           pointer is restored.
  4136.  
  4137.      code (unlink;) ( frame return -- return) compilation
  4138.           Drops the frame and move the return values down. The old frame
  4139.           pointer is restored. Leaves the colon definition. Compiled by the
  4140.           word ";".
  4141.  
  4142.      code (unlink>) ( frame return -- return) compilation
  4143.           Drops the frame and move the return values down. The old frame
  4144.           pointer is restored. Assigns the "code" type of the latest defini-
  4145.           tion and leaves the colon definition. Compiled by the word "does>".
  4146.  
  4147.    SEE ALSO
  4148.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.                                                                            63
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.    LOCALS(3X)                                                  August 1, 1990
  4163.  
  4164.  
  4165.    NOTE
  4166.      The function list is sorted in ASCII order. The type and mode of the
  4167.      entry is indicated together with the parameter stack effect.
  4168.  
  4169.    COPYING
  4170.      Copyright (C) 1990 Mikael R.K. Patel
  4171.  
  4172.      Permission is granted to make and distribute verbatim copies of this
  4173.      manual provided the copyright notice and this permission notice are
  4174.      preserved on all copies.
  4175.  
  4176.      Permission is granted to copy and distribute modified versions of this
  4177.      manual under the conditions for verbatim copying, provided also that the
  4178.      section entitled "GNU General Public License" is included exactly as in
  4179.      the original, and provided that the entire resulting derived work is
  4180.      distributed under the terms of a permission notice identical to this
  4181.      one.
  4182.  
  4183.      Permission is granted to copy and distribute translations of this manual
  4184.      into another language, under the above conditions for modified versions,
  4185.      except that the section entitled "GNU General Public License" may be
  4186.      included in a translation approved by the author instead of in the ori-
  4187.      ginal English.
  4188.  
  4189.    AUTHOR
  4190.      Mikael R.K. Patel
  4191.      Computer Aided Design Laboratory (CADLAB)
  4192.      Department of Computer and Information Science
  4193.      Linkoping University
  4194.      S-581 83 LINKOPING
  4195.      SWEDEN
  4196.      Email: mip@ida.liu.se
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.    64
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.    August 6, 1990                                                  MACROS(3X)
  4229.  
  4230.  
  4231.  
  4232.    NAME
  4233.      macros - macro expansion of colon definitions
  4234.  
  4235.    SYNOPSIS
  4236.      #include macros.f83
  4237.  
  4238.      macros
  4239.  
  4240.    DESCRIPTION
  4241.      Allows definition of macro colon definitions to reduce the overhead of
  4242.      procedure calls at run-time to the price of memory.  The macro package
  4243.      may be used, after profiling of an application, to mark the most criti-
  4244.      cal low level definitions and hereby increase performance. Macro defini-
  4245.      tion may also be used to create alias names for definitions.
  4246.  
  4247.      : .macro ( -- )
  4248.           Used in the following form:
  4249.           .macro <_m_a_c_r_o-_n_a_m_e>
  4250.           to display the internal information about the macro definition.
  4251.           The information is displayed in the following form:
  4252.           macro# <_m_a_c_r_o-_a_d_d_r_e_s_s> size: <_m_a_c_r_o-_s_i_z_e> body: <_m_a_c_r_o-_b_o_d_y-
  4253.           _a_d_d_r_e_s_s>
  4254.           Use mainly for debugging and code verification purpose.
  4255.  
  4256.      : macro ( -- )
  4257.           Used in the following form to mark the latest colon definition as a
  4258.           macro:
  4259.           : <_m_a_c_r_o-_n_a_m_e> ( ... ) ... <_m_a_c_r_o-_d_e_f_i_n_i_t_i_o_n> ... ; macro
  4260.           Used in the same way as "immediate" and other mode classifiers.
  4261.           The code section is not restricted to sequential code. Control
  4262.           structures, condition and iteration statements, are allowed as all
  4263.           branches are relative. Special care should be taken if the macro
  4264.           definition contains "exit", "tail-recurse" or "recurse" as the
  4265.           result is unpredictable when expanded.
  4266.  
  4267.      vocabulary macros ( -- )
  4268.           Vocabulary containing the macro extension definitions. Include into
  4269.           the vocabulary search chain, "context", to gain access to this
  4270.           library.
  4271.  
  4272.    INTERNALS
  4273.      Private definitions in the _m_a_c_r_o_s vocabulary;
  4274.  
  4275.      ptr +body ( macro -- addr) private
  4276.           Returns address of field in "MACRO" structure to pointer to code
  4277.           section of the macro.
  4278.  
  4279.      long +size ( macro -- addr) private
  4280.           Returns address of field in "MACRO" structure to byte size of macro
  4281.           code.
  4282.  
  4283.      struct.type MACRO ( body size -- ) private
  4284.           Structure definition used by "macro" to keep information about a
  4285.  
  4286.  
  4287.                                                                            65
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.    MACROS(3X)                                                  August 6, 1990
  4295.  
  4296.  
  4297.           macro code definition. Internal fields are "+body" and "+size".  An
  4298.           instance of this structure will perform the run-time action for a
  4299.           macro definitions. If compilation state the macro body is expanded
  4300.           into the current definition otherwise the macro body is executed.
  4301.           All macro definitions are "immediate". The "MACRO" structure type
  4302.           contains the fields "+body" and "+size".
  4303.  
  4304.    SEE ALSO
  4305.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _i_n_t_e_r_n_a_l_s(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X).
  4306.  
  4307.    EXAMPLES
  4308.      An example showing how to create macros for some additional relational
  4309.      operators:
  4310.  
  4311.           #include macros.f83
  4312.  
  4313.           macros
  4314.  
  4315.           : <> ( x y -- bool) = not ; macro
  4316.           : >= ( x y -- bool) < not ; macro
  4317.           : <= ( x y -- bool) > not ; macro
  4318.  
  4319.      The "macro" function may also be used to the allow simple aliasing and
  4320.      renaming at very low execution cost.
  4321.  
  4322.    NOTE
  4323.      The function list is sorted in ASCII order. The type and mode of the
  4324.      entries are indicated together with their parameter stack effect.
  4325.  
  4326.    WARNING
  4327.      A "macro" definition containing "exit" will work correctly in execution
  4328.      mode but expanded in a colon definition the "macro" will cause the
  4329.      definition to be exited. This is in most case not the wanted behavior.
  4330.      Special care should be taken for "macro" definitions which contain
  4331.      "exit", "recurse", and "tail-recurse".  Also argument and local vari-
  4332.      ables, and exception blocks should not be part of a macro colon defini-
  4333.      tion.
  4334.  
  4335.    COPYING
  4336.      Copyright (C) 1990 Mikael R.K. Patel
  4337.  
  4338.      Permission is granted to make and distribute verbatim copies of this
  4339.      manual provided the copyright notice and this permission notice are
  4340.      preserved on all copies.
  4341.  
  4342.      Permission is granted to copy and distribute modified versions of this
  4343.      manual under the conditions for verbatim copying, provided also that the
  4344.      section entitled "GNU General Public License" is included exactly as in
  4345.      the original, and provided that the entire resulting derived work is
  4346.      distributed under the terms of a permission notice identical to this
  4347.      one.
  4348.  
  4349.      Permission is granted to copy and distribute translations of this manual
  4350.      into another language, under the above conditions for modified versions,
  4351.  
  4352.  
  4353.    66
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.    August 6, 1990                                                  MACROS(3X)
  4361.  
  4362.  
  4363.      except that the section entitled "GNU General Public License" may be
  4364.      included in a translation approved by the author instead of in the ori-
  4365.      ginal English.
  4366.  
  4367.    AUTHOR
  4368.      Mikael R.K. Patel
  4369.      Computer Aided Design Laboratory (CADLAB)
  4370.      Department of Computer and Information Science
  4371.      Linkoping University
  4372.      S-581 83 LINKOPING
  4373.      SWEDEN
  4374.      Email: mip@ida.liu.se
  4375.  
  4376.  
  4377.  
  4378.  
  4379.  
  4380.  
  4381.  
  4382.  
  4383.  
  4384.  
  4385.  
  4386.  
  4387.  
  4388.  
  4389.  
  4390.  
  4391.  
  4392.  
  4393.  
  4394.  
  4395.  
  4396.  
  4397.  
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.                                                                            67
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.    MAPPINGS(3X)                                                August 7, 1990
  4427.  
  4428.  
  4429.  
  4430.    NAME
  4431.      mappings - vector represented mappings definitions
  4432.  
  4433.    SYNOPSIS
  4434.      #include mappings.f83
  4435.  
  4436.      mappings
  4437.  
  4438.    DESCRIPTION
  4439.      Library for mappings represented as vectors. The mapping consists of
  4440.      pairs of cells, domain and range, and is terminated by a double zero
  4441.      pair. This mapping representation is mainly used for small mapping sets
  4442.      as all operations are dependent on the size of the mapping. The pair
  4443.      zero-zero cannot be a member of the mapping.
  4444.  
  4445.      : .mapping ( mapping -- )
  4446.           Assuming that the domain is entry addresses this word will display
  4447.           the mapping as a set of pairs. The following form is used:
  4448.           { <_p_a_i_r_s> }
  4449.           where the <_p_a_i_r_s> _a_r_e _i_s _t_h_e _f_o_r_m_a_t:
  4450.           ( <_e_n_t_r_y> <_v_a_l_u_e> )
  4451.  
  4452.      : ?empty-mapping ( mapping -- bool)
  4453.           Returns "true" if the mapping is empty else "false".
  4454.  
  4455.      : ?map-mapping ( mapping block[range domain -- bool] -- )
  4456.           Conditional iterator function for mappings. The block will receive
  4457.           the pair, domain and range, as parameters and should return a
  4458.           boolean flag indicating is the iterator should terminate. The
  4459.           return value "true" will terminate the iterator.
  4460.  
  4461.      : ?range-mapping ( domain mapping -- bool)
  4462.           Returns "true" is the domain is defined and has a range in the map-
  4463.           ping else "false" is returned.
  4464.  
  4465.      : add-mapping ( range domain mapping -- )
  4466.           Adds the domain-range pair to the mapping. If the domain is already
  4467.           defined in the mapping the new range value is stored.
  4468.  
  4469.      : empty-mapping ( mapping -- )
  4470.           This word will empty the mapping by assigning the terminal pair
  4471.           first in the mapping vector.
  4472.  
  4473.      : map-mapping ( mapping block[range domain -- ] -- )
  4474.           Iterator function for mappings. The block will receive the domain-
  4475.           range pair as parameters. The block is called for all pairs in the
  4476.           mapping.
  4477.  
  4478.      : mapping ( size -- )
  4479.           Used in the following form:
  4480.           <_s_i_z_e> mapping <_n_a_m_e> ( -- mapping)
  4481.           to create a mapping variable. All operation are destructive on map-
  4482.           ping variables. The maximum number of domain-range pairs in a
  4483.  
  4484.  
  4485.    68
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.    August 7, 1990                                                MAPPINGS(3X)
  4493.  
  4494.  
  4495.           mapping set is <_s_i_z_e> - 1.
  4496.  
  4497.      vocabulary mappings ( -- )
  4498.           The vector represented mapping library vocabulary. Include into the
  4499.           vocabulary search set, "context", to allow access to these exten-
  4500.           sions.
  4501.  
  4502.      : range-mapping ( domain mapping -- addr)
  4503.           Returns the range address, "addr", for the domain in the mapping.
  4504.           The value "nil" is returned if the domain is not a member of the
  4505.           mapping.  The address may be used to manipulate the range value.
  4506.           Most mapping operations are destructive. This makes the address
  4507.           only valid until the next destructive mapping operation.
  4508.  
  4509.      : remove-mapping ( domain mapping -- )
  4510.           Removes the domain-range pair from the mapping.
  4511.  
  4512.      : size-mapping ( mapping -- num)
  4513.           Returns the number of domain-range pairs in the mapping.
  4514.  
  4515.    INTERNALS
  4516.      The _m_a_p_p_i_n_g_s library contains the following internal function to search
  4517.      a mapping and access the domain-range pair.
  4518.  
  4519.      field +domain ( mapping -- addr) private
  4520.           Access field for domain address of a domain-range pair in a mapping
  4521.           vector.
  4522.  
  4523.      field +pair ( mapping -- addr) private
  4524.           Access field for the next pair address in a mapping vector.
  4525.  
  4526.      field +range ( mapping -- addr) private
  4527.           Access field for range address of a domain-range pair in a mapping
  4528.           vector.
  4529.  
  4530.      : search-mapping ( domain mapping -- [addr1] or [domain addr2 false])
  4531.           Primitive mapping search function. Tries to locate the domain-range
  4532.           pair in the mapping. If found the pair address, "addr1", is
  4533.           returned and may be accessed with the fields; "+domain", and
  4534.           "+range". If not found the domain and the address of the terminal
  4535.           pair together with the flag "false" is returned. The function is
  4536.           used to implement the words "add-mapping", "remove-mapping",
  4537.           "?range-mapping", and "range-mapping".
  4538.  
  4539.    SEE ALSO
  4540.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _b_l_o_c_k_s(_3_X).
  4541.  
  4542.    NOTE
  4543.      The function list is sorted in ASCII order. The type and mode of the
  4544.      entry is indicated together with the parameter stack effect.
  4545.  
  4546.  
  4547.  
  4548.  
  4549.  
  4550.  
  4551.                                                                            69
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.    MAPPINGS(3X)                                                August 7, 1990
  4559.  
  4560.  
  4561.    COPYING
  4562.      Copyright (C) 1990 Mikael R.K. Patel
  4563.  
  4564.      Permission is granted to make and distribute verbatim copies of this
  4565.      manual provided the copyright notice and this permission notice are
  4566.      preserved on all copies.
  4567.  
  4568.      Permission is granted to copy and distribute modified versions of this
  4569.      manual under the conditions for verbatim copying, provided also that the
  4570.      section entitled "GNU General Public License" is included exactly as in
  4571.      the original, and provided that the entire resulting derived work is
  4572.      distributed under the terms of a permission notice identical to this
  4573.      one.
  4574.  
  4575.      Permission is granted to copy and distribute translations of this manual
  4576.      into another language, under the above conditions for modified versions,
  4577.      except that the section entitled "GNU General Public License" may be
  4578.      included in a translation approved by the author instead of in the ori-
  4579.      ginal English.
  4580.  
  4581.    AUTHOR
  4582.      Mikael R.K. Patel
  4583.      Computer Aided Design Laboratory (CADLAB)
  4584.      Department of Computer and Information Science
  4585.      Linkoping University
  4586.      S-581 83 LINKOPING
  4587.      SWEDEN
  4588.      Email: mip@ida.liu.se
  4589.  
  4590.  
  4591.  
  4592.  
  4593.  
  4594.  
  4595.  
  4596.  
  4597.  
  4598.  
  4599.  
  4600.  
  4601.  
  4602.  
  4603.  
  4604.  
  4605.  
  4606.  
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.  
  4616.  
  4617.    70
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.    August 1, 1990                                                  MEMORY(3X)
  4625.  
  4626.  
  4627.  
  4628.    NAME
  4629.      memory - tile kernel dynamic memory allocation functions
  4630.  
  4631.    SYNOPSIS
  4632.      memory
  4633.  
  4634.    DESCRIPTION
  4635.      The _t_i_l_e forth kernel support word set for dynamic memory allocation and
  4636.      reclaim from the run-time heap. Used by the kernel to allocate memory
  4637.      for tasks, entries, strings, etc.
  4638.  
  4639.      code free ( addr -- )
  4640.           Returns an allocated block of memory back to the run-time heap.
  4641.  
  4642.      code malloc ( bytes -- addr)
  4643.           Allocates a block of size "bytes" and returns a pointer to the
  4644.           memory area. Returns "nil" if the heap is saturated.
  4645.  
  4646.      vocabulary memory ( -- )
  4647.           Vocabulary containing the heap management extension. Include into
  4648.           the vocabulary search set, "context", to allow access of this
  4649.           library.
  4650.  
  4651.      code realloc ( bytes addr1 -- addr2)
  4652.           Resizes an allocated block on the heap. If the new size is larger
  4653.           than the grow size of the block a new block is allocated and the
  4654.           old blocks contains is copied and released back to the memory pool.
  4655.  
  4656.    SEE ALSO
  4657.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  4658.  
  4659.    NOTE
  4660.      The function list is sorted in ASCII order. The type and mode of the
  4661.      entries are indicated together with their parameter stack effect.
  4662.  
  4663.    COPYING
  4664.      Copyright (C) 1990 Mikael R.K. Patel
  4665.  
  4666.      Permission is granted to make and distribute verbatim copies of this
  4667.      manual provided the copyright notice and this permission notice are
  4668.      preserved on all copies.
  4669.  
  4670.      Permission is granted to copy and distribute modified versions of this
  4671.      manual under the conditions for verbatim copying, provided also that the
  4672.      section entitled "GNU General Public License" is included exactly as in
  4673.      the original, and provided that the entire resulting derived work is
  4674.      distributed under the terms of a permission notice identical to this
  4675.      one.
  4676.  
  4677.      Permission is granted to copy and distribute translations of this manual
  4678.      into another language, under the above conditions for modified versions,
  4679.      except that the section entitled "GNU General Public License" may be
  4680.      included in a translation approved by the author instead of in the
  4681.  
  4682.  
  4683.                                                                            71
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.    MEMORY(3X)                                                  August 1, 1990
  4691.  
  4692.  
  4693.      original English.
  4694.  
  4695.    AUTHOR
  4696.      Mikael R.K. Patel
  4697.      Computer Aided Design Laboratory (CADLAB)
  4698.      Department of Computer and Information Science
  4699.      Linkoping University
  4700.      S-581 83 LINKOPING
  4701.      SWEDEN
  4702.      Email: mip@ida.liu.se
  4703.  
  4704.  
  4705.  
  4706.  
  4707.  
  4708.  
  4709.  
  4710.  
  4711.  
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.  
  4748.  
  4749.    72
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.    August 1, 1990                                           MULTI-TASKING(3X)
  4757.  
  4758.  
  4759.  
  4760.    NAME
  4761.      multi-tasking - tile forth kernel extensions for concurrent programming
  4762.  
  4763.    SYNOPSIS
  4764.      #include multi-tasking.f83
  4765.  
  4766.      multi-tasking
  4767.  
  4768.    DESCRIPTION
  4769.      The _t_i_l_e kernel and forth level extensions to allow concurrent program-
  4770.      ming with tasks, condition variables, semaphores, channels and rendez-
  4771.      vous.  The tasking switch mechanism in the _t_i_l_e kernel is not time-
  4772.      multiplexed and applications are required to periodically call the task
  4773.      switch function, "detach", or, "resume", or synchronization functions
  4774.      such as semaphores, condition variables, etc.  This extension implement
  4775.      the major concurrent programming concepts and allows programming for a
  4776.      common memory or distributed model.
  4777.  
  4778.      : .task ( task -- )
  4779.           Displays the internal state of a task. The state is not the state
  4780.           of the running task as this word will display the memory structure
  4781.           of a task, and not the virtual machine state. A task cannot display
  4782.           its own state.
  4783.  
  4784.      constant >terminate ( -- addr)
  4785.           Constant containing a pointer to the terminate function. Used by
  4786.           "task" to automatically terminate task which arrive at the end of
  4787.           their task body, i.e., forth-level code section.
  4788.  
  4789.      : ?avail ( chan -- bool)
  4790.           Check whether a channel "receive" operation will not block.  Data
  4791.           is available directly. Returns "true" if data is directly available
  4792.           without waiting else "false".
  4793.  
  4794.      : ?awaiting ( -- bool) immediate
  4795.           Used in the following form:
  4796.           ?awaiting <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( -- bool)
  4797.           in a server task to check if a client task is waiting for service.
  4798.           Returns "true" if a client task is waiting else "false".
  4799.  
  4800.      : ?wait ( semaphore -- bool)
  4801.           Checks the semaphore counter to determine if a "wait" operation
  4802.           will make a task wait. Returns "true" in this case otherwise
  4803.           "false".
  4804.  
  4805.      enum.type COMMUNICATION-MODELS ( -- )
  4806.           Enumerate type used to select the operation type of a channel.  The
  4807.           models are; "ONE-TO-ONE", "ONE-TO-MANY", and "MANY-TO-ONE".
  4808.  
  4809.      struct.type CHAN ( model -- )
  4810.           Used in the following form to create a channel:
  4811.           <_c_o_m_m_u_n_i_c_a_t_i_o_n-_m_o_d_e_l> CHAN <_c_h_a_n-_n_a_m_e> ( -- chan)
  4812.           The channel is represented by two synchronization semaphores and a
  4813.  
  4814.  
  4815.                                                                            73
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.    MULTI-TASKING(3X)                                           August 1, 1990
  4823.  
  4824.  
  4825.           common data area. May be used for three major communication styles
  4826.           between tasks. These are defined by the enumeration type
  4827.           "COMMUNICATION-MODES". The operations on a channel are "send",
  4828.           "receive" and "?avail".
  4829.  
  4830.      struct.type CONDITION ( -- )
  4831.           Used as in the following form:
  4832.           CONDITION <_c_o_n_d_i_t_i_o_n-_n_a_m_e> ( -- condition)
  4833.           to create and initiate a named condition queue variable. The possi-
  4834.           ble operations, other than queue operations, on a condition queue
  4835.           are "await" and "cause".
  4836.  
  4837.      enum DELAYED ( -- enum)
  4838.           Task status code for task performing "delay". Will resume "RUNNING"
  4839.           after the "delay" operation.
  4840.  
  4841.      enum IOWAITING ( -- enum)
  4842.           Task status code for task waiting for IO. The foreground task is
  4843.           currently the only task allowed to perform io-operations, input, as
  4844.           these are not reentrant.
  4845.  
  4846.      enum MANY-TO-ONE ( -- enum)
  4847.           Selects the many-to-one communication mode of a channel. Several
  4848.           sending tasks are allowed to communicate with a service task.
  4849.  
  4850.      enum ONE-TO-ONE ( -- enum)
  4851.           The channel is to be operated in a one-to-one manner.
  4852.  
  4853.      enum ONE-TO-MANY ( -- enum)
  4854.           The channel is to be operated in a one-to-many manner. Several
  4855.           receiving tasks are possible on the channel. Data sent on the chan-
  4856.           nel is maintained from corruption.
  4857.  
  4858.      enum READY ( -- enum)
  4859.           Task status code for newly created tasks, ready for scheduling.
  4860.  
  4861.      struct.type RENDEZVOUS ( -- )
  4862.           Used in the following form:
  4863.           RENDEZVOUS <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( arg -- res)
  4864.           to create a rendezvous name. This name may then be used as a func-
  4865.           tion service by some task with "accept".
  4866.           <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( arg -- res)
  4867.           The function always takes one argument and always returns one
  4868.           result value. The service block is terminated by the word
  4869.           "accept.end".
  4870.  
  4871.      enum RUNNING ( -- enum)
  4872.           Task status code for running, scheduled, tasks.
  4873.  
  4874.      struct.type SEMAPHORE ( value -- )
  4875.           Used in the following form:
  4876.           <_v_a_l_u_e> SEMAPHORE <_s_e_m_a_p_h_o_r_e-_n_a_m_e> ( -- semaphore)
  4877.           to create and initiate a named semaphore. The possible operations
  4878.           on a semaphore are "?wait", "wait", and "signal".
  4879.  
  4880.  
  4881.    74
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.    August 1, 1990                                           MULTI-TASKING(3X)
  4889.  
  4890.  
  4891.      struct.type TASK-HEADER ( -- )
  4892.           Definition of the instance structure of a task header. Defines the
  4893.           field names for a task; "+queue", "+sp", "+s0", "+rp", "+r0",
  4894.           "+fp", and "+ep".
  4895.  
  4896.      enum.type TASK-STATUS-CODES ( -- )
  4897.           Enumerate defining the possible task status codes. The codes are;
  4898.           "READY", "DELAYED", "RUNNING", "WAITING", "IOWAITING", and "TER-
  4899.           MINATED".
  4900.  
  4901.      enum TERMINATED ( -- enum)
  4902.           Task status code for terminated tasks.
  4903.  
  4904.      enum WAITING ( -- enum)
  4905.           Task status code for task performing a generic wait operation.
  4906.  
  4907.      : accept ( -- arg) immediate
  4908.           Using in the following form:
  4909.           accept <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( arg -- res)
  4910.           ... <_s_e_r_v_i_c_e-_d_e_f_i_n_i_t_i_o_n> ...
  4911.           accept.end
  4912.           to accept calls on the rendezvous. When a client task calls the
  4913.           rendezvous the argument from client is passed to the server task
  4914.           that performed the accept.
  4915.  
  4916.      : accept.end ( res -- ) immediate
  4917.           Marks the end of an accept block in a server task. The result is
  4918.           passed to the client task and both may continue in parallel.
  4919.  
  4920.      : activate ( task -- )
  4921.           Inserts a task first in the queue of runnable task and resumed. The
  4922.           task is assumed to have be scheduled and deactivated. The task is
  4923.           now marked as "RUNNING".
  4924.  
  4925.      : await ( condition -- )
  4926.           Causes the running task to wait for a condition. The task is deac-
  4927.           tivated and places in the queue associated with the condition. The
  4928.           task status is "WAITING" while in the queue.
  4929.  
  4930.      task.field byte ( -- )
  4931.           Used in the following form:
  4932.           byte <_u_s_e_r-_n_a_m_e> ( -- addr)
  4933.           within a task type definitions. Creates a user variable access name
  4934.           to a byte.
  4935.  
  4936.      : bytes ( size -- )
  4937.           Used in the following form to create named local structures and
  4938.           data within task instances:
  4939.           <_n_u_m_b_e_r> bytes <_u_s_e_r-_f_i_e_l_d-_n_a_m_e> ( -- addr)
  4940.           Should only be used within the layout section of a task type.
  4941.  
  4942.      : cause ( condition -- )
  4943.           Activates the first waiting task in the condition queue.  The task
  4944.           status will become "RUNNING".
  4945.  
  4946.  
  4947.                                                                            75
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.    MULTI-TASKING(3X)                                           August 1, 1990
  4955.  
  4956.  
  4957.      : deactivate ( queue task -- )
  4958.           Removes a task from the queue of runnable task and inserts it into
  4959.           the given queue. The task is marked as "WAITING".  The next runn-
  4960.           able task is resumed.
  4961.  
  4962.      : delay ( n -- )
  4963.           Delays a task a number of task switches. The delay is not real-time
  4964.           but relative time. The task status is "DELAYED" during the delay.
  4965.  
  4966.      code detach ( -- )
  4967.           Deactivate the current running task and resumes the next task in
  4968.           the queue over runnable tasks.
  4969.  
  4970.      task.field enum ( -- )
  4971.           Used in the following form:
  4972.           enum <_u_s_e_r-_n_a_m_e> ( -- addr)
  4973.           within a task type definitions. Creates a user variable access name
  4974.           to an enumerative, four bytes counter.
  4975.  
  4976.      variable foreground ( -- addr)
  4977.           Variable containing a pointer to the foreground task.
  4978.  
  4979.      code fork ( -- task)
  4980.           Copies the current task and returns a pointer to it. The child task
  4981.           will receive a pointer to the parent task as result of fork. The
  4982.           parent will receive a pointer to the child task. The child is
  4983.           scheduled directly.
  4984.  
  4985.      : join ( task -- )
  4986.           Delay a task until the task given as parameter terminates.  The
  4987.           task status is "WAITING" during the join delay.
  4988.  
  4989.      task.field long ( -- )
  4990.           Used in the following form:
  4991.           long <_u_s_e_r-_n_a_m_e> ( -- addr)
  4992.           within a task type definitions. Creates a user variable access name
  4993.           to a long, four bytes.
  4994.  
  4995.      task.field ptr ( -- )
  4996.           Used in the following form:
  4997.           ptr <_u_s_e_r-_n_a_m_e> ( -- addr)
  4998.           within a task type definitions. Creates a user variable access name
  4999.           to a pointer, four bytes.
  5000.  
  5001.      vocabulary multi-tasking ( -- )
  5002.           Vocabulary containing the multi-tasking extensions to the Forth-83
  5003.           Standard. These extensions are realized both as primitives and on
  5004.           the forth level.
  5005.  
  5006.      : mutex ( -- )
  5007.           Used in the following form:
  5008.           mutex <_s_e_m_a_p_h_o_r_e-_n_a_m_e> ( -- semaphore)
  5009.           to create a semaphore for mutual exclusion. Should not be used
  5010.           within other structures as this definition is not a structure
  5011.  
  5012.  
  5013.    76
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.    August 1, 1990                                           MULTI-TASKING(3X)
  5021.  
  5022.  
  5023.           definition but a code definition.
  5024.  
  5025.      : new-task ( -- task)
  5026.           Used in the following form:
  5027.           new-task <_t_a_s_k-_t_y_p_e-_n_a_m_e> ( -- task)
  5028.           to create a new task instance of a task type. Allocates and
  5029.           schedules the task instance.
  5030.  
  5031.      : receive ( chan -- data)
  5032.           Receives data from channel. Will wait until sender has performed
  5033.           "send".
  5034.  
  5035.      : resume ( task -- )
  5036.           Activates the given task. The task must be a member of the runnable
  5037.           tasks, i.e., scheduled and waiting for activation.
  5038.  
  5039.      variable running ( -- addr)
  5040.           Variable containing a pointer to the current running task.
  5041.  
  5042.      code schedule ( task -- )
  5043.           Schedules the given task and activates it immediately.
  5044.  
  5045.      : send ( data chan -- )
  5046.           Sends data on a channel. Sender will wait until receiver has per-
  5047.           formed "receive".
  5048.  
  5049.      : signal ( semaphore -- )
  5050.           If there is a waiting task on the semaphore this task is resumed
  5051.           else the semaphore counter is incremented.
  5052.  
  5053.      : struct ( -- )
  5054.           Creates a named user variable of a structure size. Use in the fol-
  5055.           lowing form:
  5056.           struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> <_u_s_e_r-_n_a_m_e> ( -- addr)
  5057.  
  5058.      code task ( users parameters returns code -- task)
  5059.           Used to create a task instance. The "users" parameter defines the
  5060.           size of the task local variable area in bytes. The "parameters" and
  5061.           "returns" arguments define the size of the tasks parameter and
  5062.           return stack in "cells". Last the "code" parameter is a pointer to
  5063.           forth-level code. Returns a pointer to a task.  The task is allo-
  5064.           cated from the run-time heap and not the dictionary.  The "memory"
  5065.           extension word "free" should be used to reclaim the allocated area
  5066.           if needed.
  5067.  
  5068.      : task.body ( -- )
  5069.           Used within a task type definition structure to indicate the begin-
  5070.           ning of the task body part and the end of the user variables.
  5071.  
  5072.      : task.end ( -- )
  5073.           Ends a task type definition.
  5074.  
  5075.      struct.type task.type ( parameters returns -- )
  5076.           Used in the following form to start the definition of a task type:
  5077.  
  5078.  
  5079.                                                                            77
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.    MULTI-TASKING(3X)                                           August 1, 1990
  5087.  
  5088.  
  5089.           <_p_a_r_a_m_e_t_e_r_s> <_r_e_t_u_r_n_s> task.type <_t_a_s_k-_t_y_p_e-_n_a_m_e>
  5090.           { <_u_s_e_r-_v_a_r_i_a_b_l_e_s> }
  5091.           task.body
  5092.           <_t_a_s_k-_b_o_d_y-_d_e_f_i_n_i_t_i_o_n>
  5093.           task.end
  5094.           The two parameters, parameters and returns, define the size in
  5095.           cells of these two areas within a task instance. Local user area is
  5096.           defined by the task field names; "byte", "bytes", "word", "long",
  5097.           "enum", "ptr", and "struct".
  5098.  
  5099.      code terminate ( -- )
  5100.           Terminates the current running task and resumes the next task in
  5101.           the runnable task queue.
  5102.  
  5103.      code user ( offset -- )
  5104.           Used in the following form to create a local, user, variable within
  5105.           the task instance:
  5106.           <_o_f_f_s_e_t> user <_u_s_e_r-_n_a_m_e> ( -- addr)
  5107.           The offset is a relative address from the task pointer.
  5108.  
  5109.      : wait ( semaphore -- )
  5110.           Dequeues the task and places it into the semaphore waiting queue if
  5111.           the semaphore counter is zero otherwise the counter is decrements
  5112.           and the task continues. The task status is "WAITING" during the
  5113.           semaphore wait delay.
  5114.  
  5115.           : who ( -- ) Displays the current queue of runnable tasks.
  5116.  
  5117.      task.field word ( -- )
  5118.           Used in the following form:
  5119.           word <_u_s_e_r-_n_a_m_e> ( -- addr)
  5120.           within a task type definitions. Creates a user variable access name
  5121.           to a word, two bytes.
  5122.  
  5123.    INTERNALS
  5124.      Private definitions in the _m_u_l_t_i-_t_a_s_k_i_n_g vocabulary;
  5125.  
  5126.      struct CHAN +arg ( rendezvous -- addr) private
  5127.           Structure field within a rendezvous which is the channel for argu-
  5128.           ment passing to the server task.
  5129.  
  5130.      ptr +body ( task.type -- addr) private
  5131.           Field access to task type pointer to task body code.
  5132.  
  5133.      long +count ( semaphore -- addr) private
  5134.           Field access to semaphore value.
  5135.  
  5136.      long +data ( chan -- addr) private
  5137.           Field access to the common data area. Used as holding place for
  5138.           data sent until received.
  5139.  
  5140.      ptr +ep ( task -- addr) private
  5141.           Field access of task exception frame pointer.
  5142.  
  5143.  
  5144.  
  5145.    78
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.    August 1, 1990                                           MULTI-TASKING(3X)
  5153.  
  5154.  
  5155.      ptr +fp ( task -- addr) private
  5156.           Field access of task argument frame pointer.
  5157.  
  5158.      ptr +ip ( task -- addr) private
  5159.           Field access of task instruction pointer.
  5160.  
  5161.      struct CONDITION +not.zero ( semaphore -- addr) private
  5162.           Field access to semaphore condition for tasks waiting for not zero
  5163.           count.
  5164.  
  5165.      long +parameters ( task.type -- addr) private
  5166.           Field access of number of cells for parameter stack of task type.
  5167.  
  5168.      struct QUEUE +queue ( task -- addr) private
  5169.           Field access of system queue of task instances.
  5170.  
  5171.      ptr +r0 ( task -- addr) private
  5172.           Field access of task return stack bottom pointer.
  5173.  
  5174.      struct SEMAPHORE +received ( chan -- addr) private
  5175.           Field access to the received synchronization semaphore.
  5176.  
  5177.      struct CHAN +res ( rendezvous -- addr) private
  5178.           Structure field within a rendezvous which is the channel for result
  5179.           passing from the server task to the client task.
  5180.  
  5181.      long +returns ( task.type -- addr) private
  5182.           Field access of number of cells for return stack of task type.
  5183.  
  5184.      ptr +rp ( task -- addr) private
  5185.           Field access of task return stack pointer.
  5186.  
  5187.      ptr +s0 ( task -- addr) private
  5188.           Field access of task bottom of parameter stack pointer.
  5189.  
  5190.      struct SEMAPHORE +sent ( chan -- addr) private
  5191.           Field access to the sent synchronization semaphore.
  5192.  
  5193.      ptr +sp ( task -- addr) private
  5194.           Field access of task parameter stack pointer.
  5195.  
  5196.      enum +status ( task -- addr) private
  5197.           Field access of task status. See "TASK-STATUS-CODES" for possible
  5198.           codes.
  5199.  
  5200.      long +users ( task.type -- addr) private
  5201.           Field access of number of bytes for user area of task type.
  5202.  
  5203.      struct CONDITION +waiting ( condition -- queue) private
  5204.           Field access to condition queue of waiting tasks.
  5205.  
  5206.      : make-task ( task.type -- task) private
  5207.           Creates an anonymous task given a task type instance. Used in the
  5208.           following form:
  5209.  
  5210.  
  5211.                                                                            79
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.    MULTI-TASKING(3X)                                           August 1, 1990
  5219.  
  5220.  
  5221.           as <_t_a_s_k-_t_y_p_e-_n_a_m_e> make-task ( -- task)
  5222.  
  5223.      : task.field ( size -- ) private
  5224.           Fix size field meta-word. Used to create primary set of field type
  5225.           names, "byte", "word", "long", "ptr", and "enum". Should only be
  5226.           used for definitions internal to "multi-tasking".
  5227.  
  5228.    SEE ALSO
  5229.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _e_n_u_m_e_r_a_t_e_s(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X),
  5230.      _q_u_e_u_e_s(_3_X).
  5231.  
  5232.    EXAMPLES
  5233.      For examples see the test and benchmark library (directory "tst").
  5234.  
  5235.    NOTE
  5236.      The function list is sorted in ASCII order. The type and mode of the
  5237.      entries are indicated together with their parameter stack effect.
  5238.  
  5239.    COPYING
  5240.      Copyright (C) 1990 Mikael R.K. Patel
  5241.  
  5242.      Permission is granted to make and distribute verbatim copies of this
  5243.      manual provided the copyright notice and this permission notice are
  5244.      preserved on all copies.
  5245.  
  5246.      Permission is granted to copy and distribute modified versions of this
  5247.      manual under the conditions for verbatim copying, provided also that the
  5248.      section entitled "GNU General Public License" is included exactly as in
  5249.      the original, and provided that the entire resulting derived work is
  5250.      distributed under the terms of a permission notice identical to this
  5251.      one.
  5252.  
  5253.      Permission is granted to copy and distribute translations of this manual
  5254.      into another language, under the above conditions for modified versions,
  5255.      except that the section entitled "GNU General Public License" may be
  5256.      included in a translation approved by the author instead of in the ori-
  5257.      ginal English.
  5258.  
  5259.    AUTHOR
  5260.      Mikael R.K. Patel
  5261.      Computer Aided Design Laboratory (CADLAB)
  5262.      Department of Computer and Information Science
  5263.      Linkoping University
  5264.      S-581 83 LINKOPING
  5265.      SWEDEN
  5266.      Email: mip@ida.liu.se
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.  
  5277.    80
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.    September 3, 1990                                              OBJECTS(3X)
  5285.  
  5286.  
  5287.  
  5288.    NAME
  5289.      objects - object oriented programming extension
  5290.  
  5291.    SYNOPSIS
  5292.      #include objects.f83
  5293.  
  5294.      objects
  5295.  
  5296.    DESCRIPTION
  5297.      This library realizes the popular class-instance model of object
  5298.      oriented programming. The "world" is divided into classes and instances.
  5299.      The classes hold all common information for the instances. This informa-
  5300.      tion is the instance variable fields and the messages an instance can
  5301.      answer. The answer of a message is called a method. A method may call
  5302.      the super class implementation of a message with the prefix word
  5303.      "super". This creates a static binding of the message to the super
  5304.      class. A messages require the object as the top most parameter stack
  5305.      element and will locate an appropriate method at run-time (late-
  5306.      binding).
  5307.  
  5308.      : .class ( object -- )
  5309.           Displays the name of the class of an object on the current output
  5310.           stream.
  5311.  
  5312.      : .message ( message -- )
  5313.           Displays the name of the message on the current output stream. May
  5314.           be used by the error message "doesNotUnderstand" which receives a
  5315.           message as parameter.
  5316.  
  5317.      : align ( -- )
  5318.           Instance variable layout control word. Used to align the next field
  5319.           to an even byte boundary within the definition section of a class.
  5320.  
  5321.      : basicInstanceSize ( class -- num)
  5322.           Returns the instance size in bytes.
  5323.  
  5324.      subclass.field byte ( -- )
  5325.           Used within the instance variable section of a class definition to
  5326.           create a byte field name.
  5327.           byte <_n_a_m_e> ( object -- addr)
  5328.           The field will require an object and will return the address of the
  5329.           byte within the object.
  5330.  
  5331.      : bytes ( size -- )
  5332.           Used within the instance variable section of a class definition to
  5333.           create a byte vector field name.
  5334.           <_s_i_z_e> bytes <_n_a_m_e> ( object -- addr)
  5335.           The field will require an object and will return the address of the
  5336.           byte vector within the object.
  5337.  
  5338.      : canUnderstand ( message class -- bool)
  5339.           Returns "true" if the class can understand the message (there
  5340.           exists a method) else "false".
  5341.  
  5342.  
  5343.                                                                            81
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.    OBJECTS(3X)                                              September 3, 1990
  5351.  
  5352.  
  5353.      : class ( object -- addr)
  5354.           Returns the class address for the object. The class is implemented
  5355.           as a prototype.
  5356.  
  5357.      : dispose-instance ( object -- )
  5358.           Used in the following form:
  5359.           <_o_b_j_e_c_t> dispose-instance ( -- )
  5360.           to reclaim memory allocated for an object. The object should not be
  5361.           accessed after this functions. Only objects allocated with the word
  5362.           "new-instance" may be reclaimed. Objects created with the word
  5363.           "instance" should be regarded as global variables.
  5364.  
  5365.      forward doesNotUnderstand ( message object -- )
  5366.           Forward declared error message. Sent to an object when the message
  5367.           lookup mechanism fails. May be used to implement "proxy" objects.
  5368.  
  5369.      subclass.field enum ( -- )
  5370.           Used within the instance variable section of a class definition to
  5371.           create a enumerate field name.
  5372.           enum <_n_a_m_e> ( object -- addr)
  5373.           The field will require an object and will return the address of the
  5374.           enumerate within the object.
  5375.  
  5376.      forward initiate ( ... object -- )
  5377.           This word is called by "new-instance" and "instance" and should be
  5378.           a message used to initiate the newly created object.
  5379.  
  5380.      : instance ( class -- )
  5381.           Used in the following form:
  5382.           <_c_l_a_s_s> instance <_n_a_m_e> ( -- object)
  5383.           to create a named instance of a class. The message "initiate" is
  5384.           send to the newly created instance. This message must be answered.
  5385.  
  5386.      subclass.field long ( -- )
  5387.           Used within the instance variable section of a class definition to
  5388.           create a long integer field name.
  5389.           long <_n_a_m_e> ( object -- addr)
  5390.           The field will require an object and will return the address of the
  5391.           long integer within the object.
  5392.  
  5393.      : message ( -- )
  5394.           Used in the following form:
  5395.           message <_n_a_m_e> ( ... object -- ... )
  5396.           to create a message. The message may be passed to an object as a
  5397.           normal function call. The top most parameter is always required to
  5398.           be an object.  A method for the message is located at run-time giv-
  5399.           ing late binding, and polymorphism.
  5400.  
  5401.      : method ( -- )
  5402.           Used in the following form within the definition section of a
  5403.           class:
  5404.           method <_m_e_s_s_a_g_e> ( ... object -- ...) ... ;
  5405.           to define a method for the message. The method will receive the
  5406.           object, self, as the first parameter. To pass the message to the
  5407.  
  5408.  
  5409.    82
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.    September 3, 1990                                              OBJECTS(3X)
  5417.  
  5418.  
  5419.           superclass the message prefix word "super" may be used. This is
  5420.           common practice in object oriented programming. The method defini-
  5421.           tion should not contain the words "recurse", "tail-recurse", and
  5422.           "exception>" as these require an entry binding.
  5423.  
  5424.      : new-instance ( class -- object)
  5425.           Used in the following form:
  5426.           <_c_l_a_s_s> new-instance ( -- object)
  5427.           to create an instance of a class. The message "initiate" is sent to
  5428.           the newly created instance. This message must be answered or the
  5429.           error message "doesNotUnderstand" is sent to the instance. The
  5430.           object may be reclaimed with the word "dispose-instance".
  5431.  
  5432.      vocabulary objects ( -- )
  5433.           The object oriented extension vocabulary. Include to the vocabulary
  5434.           search set, "context", to allow programming in the object oriented
  5435.           programming paradigm.
  5436.  
  5437.      subclass.field ptr  ( -- )
  5438.           Used within the instance variable section of a class definition to
  5439.           create a pointer field name.
  5440.           ptr <_n_a_m_e> ( object -- addr)
  5441.           The field will require an object and will return the address of the
  5442.           pointer field within the object.
  5443.  
  5444.      : send ( object message class -- object)
  5445.           Primitive message sending function. Used by the normal message-
  5446.           passing, "message", mechanism to locate and apply a method.
  5447.  
  5448.      : subclass ( superclass -- )
  5449.           Used in the following form:
  5450.           <_c_l_a_s_s> subclass <_n_a_m_e>
  5451.           { <_i_n_s_t_a_n_c_e-_v_a_r_i_a_b_l_e-_f_i_e_l_d> }
  5452.           { <_m_e_t_h_o_d> }
  5453.           subclass.end
  5454.           to initiate the definition of a class. This definition should con-
  5455.           tain two major sections; the instance variable fields, and the
  5456.           instance methods. All field names will become local to the class.
  5457.           The words "byte", "bytes", "enum", "word", "long" and "ptr" should
  5458.           be used to create instance variable field names. These will require
  5459.           an object pointer and will return the address of the corresponding
  5460.           field. The field should then be manipulated with the memory access
  5461.           functions.  The word "align" may be used before a field name defin-
  5462.           ition to align it to an even byte boundary. The method definition
  5463.           section may contain implementations of messages. A method may be
  5464.           viewed as a normal colon definition with the extension that many
  5465.           definitions, methods, for the same name, message, may exist simul-
  5466.           taneous and the selection is performed at run-time (late binding).
  5467.           The method should always receive the object, self, as the top most
  5468.           parameter. The message prefix word "super" may be used to call the
  5469.           super class implementation of a method. This binding is static. The
  5470.           word "this-class" may be used to access the current class. The
  5471.           method may not use the words "recurse", "tail-recurse", and "excep-
  5472.           tions>" as these require an entry binding.
  5473.  
  5474.  
  5475.                                                                            83
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.    OBJECTS(3X)                                              September 3, 1990
  5483.  
  5484.  
  5485.      : subclass.end ( -- )
  5486.           Used in the following form:
  5487.           <_c_l_a_s_s> subclass <_n_a_m_e>
  5488.           { <_i_n_s_t_a_n_c_e-_v_a_r_i_a_b_l_e-_f_i_e_l_d> }
  5489.           { <_m_e_t_h_o_d> }
  5490.           subclass.end
  5491.           to finish the definition of a class. Additional methods and fields
  5492.           should not be defined after this word.
  5493.  
  5494.      : super ( -- ) immediate compilation
  5495.           Used in the following form within a method definition:
  5496.           super <_m_e_s_s_a_g_e>
  5497.           to call a method for a message in the superclass. This word should
  5498.           only be used inside of method definitions.
  5499.  
  5500.      : superclass ( class1 -- class2)
  5501.           Returns the address super class of the class. The value is "nil"
  5502.           for a root class.
  5503.  
  5504.      : this-class ( -- class) immediate
  5505.           Returns the address of the current definitions class. Will return
  5506.           "nil" outside of a class definition.
  5507.  
  5508.      subclass.field word ( -- )
  5509.           Used within the instance variable definition section of a class to
  5510.           create a word integer field name.
  5511.           word <_n_a_m_e> ( object -- addr)
  5512.           The field will require an object and will return the address of the
  5513.           word integer within the object.
  5514.  
  5515.    INTERNALS
  5516.      Private definitions in the _o_b_j_e_c_t_s vocabulary;
  5517.  
  5518.      : allot-instance ( class -- object) private
  5519.           Used in the following form:
  5520.           <_c_l_a_s_s> allot-instance ( -- object)
  5521.           to create an instance of a class. The message "initiate" is sent to
  5522.           the newly created instance. This message must be answered or the
  5523.           error message "doesNotUnderstand" is sent to the instance. The
  5524.           object is allocated from the dictionary area.
  5525.  
  5526.      slot instance-size: ( class -- num) private
  5527.           Slot for a class (prototype) containing the number of byte for an
  5528.           instance of this class.
  5529.  
  5530.      slot instance-variables: ( class -- entry) private
  5531.           Slot for a class (prototype) containing a pointer to the last
  5532.           defined instance variable field entry. The list of variables is
  5533.           terminated by the class itself.
  5534.  
  5535.      : subclass.field ( size -- ) private
  5536.           Use to create instance variable field type names. These field types
  5537.           should only be used within a class definition.
  5538.  
  5539.  
  5540.  
  5541.    84
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.    September 3, 1990                                              OBJECTS(3X)
  5549.  
  5550.  
  5551.      variable the-class ( -- addr) private
  5552.           Used within a class definition section to access the address of the
  5553.           current definition class. Outside of the definition section the
  5554.           variable will have the value "nil".
  5555.  
  5556.    SEE ALSO
  5557.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _p_r_o_t_o_t_y_p_e_s(_3_X).
  5558.  
  5559.    NOTE
  5560.      The function list is sorted in ASCII order. The type and mode of the
  5561.      entries are indicated together with their parameter stack effect.
  5562.  
  5563.    WARNING
  5564.      This library contains forward declared words which should be supplied.
  5565.      Check that your definitions vocabulary comes before the "objects" voca-
  5566.      bulary when defining these words.
  5567.  
  5568.    COPYING
  5569.      Copyright (C) 1990 Mikael R.K. Patel
  5570.  
  5571.      Permission is granted to make and distribute verbatim copies of this
  5572.      manual provided the copyright notice and this permission notice are
  5573.      preserved on all copies.
  5574.  
  5575.      Permission is granted to copy and distribute modified versions of this
  5576.      manual under the conditions for verbatim copying, provided also that the
  5577.      section entitled "GNU General Public License" is included exactly as in
  5578.      the original, and provided that the entire resulting derived work is
  5579.      distributed under the terms of a permission notice identical to this
  5580.      one.
  5581.  
  5582.      Permission is granted to copy and distribute translations of this manual
  5583.      into another language, under the above conditions for modified versions,
  5584.      except that the section entitled "GNU General Public License" may be
  5585.      included in a translation approved by the author instead of in the ori-
  5586.      ginal English.
  5587.  
  5588.    AUTHOR
  5589.      Mikael R.K. Patel
  5590.      Computer Aided Design Laboratory (CADLAB)
  5591.      Department of Computer and Information Science
  5592.      Linkoping University
  5593.      S-581 83 LINKOPING
  5594.      SWEDEN
  5595.      Email: mip@ida.liu.se
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.  
  5605.  
  5606.  
  5607.                                                                            85
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.    PARSER(3X)                                                 August 21, 1990
  5615.  
  5616.  
  5617.  
  5618.    NAME
  5619.      parser - top down parser with backtrack and semantic binding
  5620.  
  5621.    SYNOPSIS
  5622.      #include parser.f83
  5623.  
  5624.      parser
  5625.  
  5626.    DESCRIPTION
  5627.      Top down parser with backtrack and semantic attributed grammar.
  5628.      Translates string using a grammar to a sequence of semantic actions in
  5629.      forth.
  5630.  
  5631.      variable >break ( -- addr)
  5632.           Pointer to scanner break function. The default function is the
  5633.           parser break function "break-on-special". The parser also supports
  5634.           the forth entry break function "break-on-white-space".
  5635.  
  5636.      variable >buffer ( -- addr)
  5637.           Current buffer position during parsing. Pointer into the "buffer".
  5638.  
  5639.      variable >skip ( -- addr)
  5640.           Pointer to scanner skip function. The default function is the
  5641.           parser skip function "skip-white-space".
  5642.  
  5643.      : bind ( addr -- )
  5644.           Appends the given parameter as a literal value to the list of
  5645.           semantics. Should be used by "primary" functions to bind scanned
  5646.           data such as numbers, strings, and identifiers.
  5647.  
  5648.      : break-on-special ( addr -- bool)
  5649.           Default break character function for scan. Returns "true" if the
  5650.           current character is a break character. The default function will
  5651.           return "false" if the character is a letter or a digit else true.
  5652.  
  5653.      : break-on-white-space ( addr -- bool)
  5654.           Alternative break character function for scan used by entry to scan
  5655.           for forth words. Returns "true" if the current character in the
  5656.           input buffer is a white space (less or equal to a space character).
  5657.           Used by the parser primary "entry".
  5658.  
  5659.      variable buffer ( -- addr)
  5660.           Parser scanner buffer pointer. May be assigned to an application
  5661.           buffer to parse.
  5662.  
  5663.      symbol empty ( -- symbol)
  5664.           Symbol for basic primary function; <_e_m_p_t_y>. Basic primary function
  5665.           which always returns "true".
  5666.  
  5667.      : end.syntax ( -- ) immediate compilation
  5668.           Marks the end of a syntax rule definition.
  5669.  
  5670.      : end.primary ( -- ) immediate compilation
  5671.  
  5672.  
  5673.    86
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.    August 21, 1990                                                 PARSER(3X)
  5681.  
  5682.  
  5683.           Marks the end of a primary function.
  5684.  
  5685.      symbol entry ( -- symbol)
  5686.           Symbol for basic primary function; <_e_n_t_r_y>. Basic primary function
  5687.           which returns "true" is the next token is an entry in the current
  5688.           vocabulary search path. The next token may have a vocabulary pre-
  5689.           fix. In this case the token is located in the given vocabulary. The
  5690.           entry pointer is appended as a literal to the list of semantics.
  5691.  
  5692.      symbol eoln ( -- symbol)
  5693.           Symbol for basic primary function; <_e_o_l_n>. Basic primary function
  5694.           which returns "true" when no more tokens exist in the parser
  5695.           buffer.
  5696.  
  5697.      symbol identifier ( -- symbol)
  5698.           Symbol for basic primary function; <_i_d_e_n_t_i_f_i_e_r>. Basic primary
  5699.           function which returns "true" if the next token is an identifier.
  5700.           The string address and length are appended as literals to the list
  5701.           of semantics.
  5702.  
  5703.      : interact ( symbol -- )
  5704.           Interaction top loop using the parameter symbol as parse goal.  The
  5705.           top loop will perform the following operation; read line from input
  5706.           stream, parse the line with the given goal syntax, and if a parse
  5707.           is possible execute the semantic actions.  The top loop is repeated
  5708.           until the token "forth" is given.
  5709.  
  5710.      symbol number ( -- symbol)
  5711.           Symbol for basic primary function; <_n_u_m_b_e_r>. Basic primary function
  5712.           which returns "true" if the next token is a number. The value of
  5713.           the number is appended as a literal to the list of semantics.
  5714.  
  5715.      : no-semantic ( -- true)
  5716.           Parser virtual machine instruction for the end of a rule with no
  5717.           semantic function. Will always return "true" and exit the current
  5718.           rule.
  5719.  
  5720.      : non-terminal ( symbol -- [] or [false])
  5721.           Parser virtual machine instruction for parsing a non-terminal sym-
  5722.           bol. Will continue the execution of the rule if "true" else return
  5723.           to the syntax function.
  5724.  
  5725.      parser ( -- )
  5726.           The Top Down Parser Virtual Machine definitions vocabulary. Include
  5727.           into the vocabulary search set, "context", to allow access to this
  5728.           library.
  5729.  
  5730.      : parse ( symbol -- [semantics] or [false])
  5731.           Given a symbol reference, parses the current buffer contents and if
  5732.           parsed the generated list of semantics is returned else false.  The
  5733.           list of semantics is a block of code and may be executed with the
  5734.           block function call.
  5735.  
  5736.      : parse" ( symbol -- ) execution
  5737.  
  5738.  
  5739.                                                                            87
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.    PARSER(3X)                                                 August 21, 1990
  5747.  
  5748.  
  5749.           Used in the following form:
  5750.           <_s_y_m_b_o_l> parse" <_p_a_r_s_e _s_t_r_i_n_g> "
  5751.           to give a string to parse. The string is parsed with the given goal
  5752.           syntax symbol and if parsed the semantics actions are called else
  5753.           an error message is given and an abort is performed.
  5754.  
  5755.      : primary ( symbol -- )
  5756.           Used in the following form:
  5757.           <_s_y_m_b_o_l> primary ( -- bool) ... <_d_e_f_i_n_i_t_i_o_n> ... end.primary
  5758.           to define a primary function. These are used by the parser when a
  5759.           syntax definition is missing or fails to continue the parse pro-
  5760.           cess. The primary function should scan the buffer at the current
  5761.           position and signal to the parser if the next token is accepted or
  5762.           not. The function should return true when accepting the next token
  5763.           and false when rejecting it. The word "bind" should be used to cap-
  5764.           ture data and pass it to the semantic actions.
  5765.  
  5766.      : scan ( -- addr n)
  5767.           Token scanning function. Returns address to token in buffer and
  5768.           length of token. If the buffer contains no more characters a zero
  5769.           length is returned.
  5770.  
  5771.      : semantic ( -- true)
  5772.           Parser virtual machine instruction for appending the succeeding
  5773.           function to the list of semantics. Will always return "true" and
  5774.           exit the current rule.
  5775.  
  5776.      : semantic, ( addr -- )
  5777.           Appends the given semantic action function to the list of seman-
  5778.           tics.
  5779.  
  5780.      : skip-white-space ( addr1 -- addr2)
  5781.           Default skip character function of scanner. Skips all characters
  5782.           until a character which is greater than blank or null. The parame-
  5783.           ter is the current position in the scanner buffer. The return value
  5784.           is address to the first non-skip character or a null character.
  5785.  
  5786.      struct.type symbol ( -- )
  5787.           Structure definition of a parser symbol. Used in the following
  5788.           form:
  5789.           symbol <_n_a_m_e> ( -- symbol)
  5790.           to create a symbol which may occur in syntax and primary defini-
  5791.           tions.
  5792.  
  5793.      : syntax ( symbol -- )
  5794.           Used in the following form:
  5795.           <_s_y_m_b_o_l> syntax ... <parser virtual machine definition> ...
  5796.           end.syntax
  5797.           to generate a grammar rule. The definition should contain the
  5798.           parser virtual machine definitions; "terminal", "non-terminal",
  5799.           "zero-or-one", "zero-or-more", and ended with one of the following;
  5800.           "semantic", and "no-semantic". Each of these functions takes a sym-
  5801.           bol as a parameter.
  5802.  
  5803.  
  5804.  
  5805.    88
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.    August 21, 1990                                                 PARSER(3X)
  5813.  
  5814.  
  5815.      : terminal ( symbol -- [] or [false])
  5816.           Parser virtual machine instruction for matching a terminal symbol.
  5817.           Will continue the execution of the rule if "true" else return to
  5818.           the syntax function.
  5819.  
  5820.      : zero-or-more ( symbol -- )
  5821.           Parser virtual machine instruction for parsing a non-terminal sym-
  5822.           bol zero or more times. Will always continue the execution of the
  5823.           rule.
  5824.  
  5825.      : zero-or-one ( symbol -- )
  5826.           Parser virtual machine instruction for parsing a non-terminal sym-
  5827.           bol zero or one time. Will always continue the execution of the
  5828.           rule.
  5829.  
  5830.    INTERNALS
  5831.      The _p_a_r_s_e_r vocabulary contains the following private definitions.
  5832.  
  5833.      ptr +entry ( symbol -- addr) private
  5834.           Access field to entry reference in a "symbol" structure.
  5835.  
  5836.      ptr +next ( rule -- addr) private
  5837.           Access field to next rule in syntax list in a "rule" structure.
  5838.  
  5839.      ptr +primary ( symbol -- addr) private
  5840.           Access field to primary function in a "symbol" structure.
  5841.  
  5842.      ptr +rule ( rule -- addr) private
  5843.           Access field to virtual parse machine code for a rule structure.
  5844.  
  5845.      ptr +syntax ( symbol -- addr) private
  5846.           Access field to syntax rule list in a symbol structure.
  5847.  
  5848.      variable >semantics ( -- addr) private
  5849.           Pointer to end of list of semantics in the vector "semantics".
  5850.  
  5851.      : backtrack ( x y  -- ) private
  5852.           Backtracks the parser to the state given by the environment block
  5853.           on stack captured by "seize".
  5854.  
  5855.      create interact-buffer ( -- addr) private
  5856.           Internal buffer used for interaction top loop.
  5857.  
  5858.      constant interact-buffer-size ( -- num) private
  5859.           Size of internal buffer used for interaction top loop.
  5860.  
  5861.      : primary ( symbol -- bool) private
  5862.           Executes a symbols primary function. Returns the value from this
  5863.           function if available else "false".
  5864.  
  5865.      : release ( rule x y -- ) private
  5866.           Releases an environment block build by a "seize" call.
  5867.  
  5868.      struct.type rule ( -- ) private
  5869.  
  5870.  
  5871.                                                                            89
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.    PARSER(3X)                                                 August 21, 1990
  5879.  
  5880.  
  5881.           Structure definition of a syntax rule.
  5882.  
  5883.      : rule ( rule -- bool) private
  5884.           Executes the parser virtual machine code definition for a rule.
  5885.  
  5886.      : seize ( rule -- rule x y rule) private
  5887.           Captures the current state of the parser. This environment may be
  5888.           released or used to "backtrack" the parser.
  5889.  
  5890.      create semantics ( -- addr) private
  5891.           List of semantic actions. Collected during the parse and is
  5892.           returned by parse when it succeeds. The list is a compiled block of
  5893.           forth definitions.
  5894.  
  5895.      constant semantics-size ( -- num) private
  5896.           Size of list of semantics.
  5897.  
  5898.      : syntax ( symbol -- bool) private
  5899.           Given a symbol performs the basic top down parsing with the symbols
  5900.           syntax definition as goal. Returns "true" if the syntax parse
  5901.           succeeds else false.
  5902.  
  5903.      create token ( -- addr) private
  5904.           Internal buffer for tokens used by "entry" primary function.
  5905.  
  5906.      constant token-size ( -- num) private
  5907.           Size of internal buffer for token. Used by basic primary function
  5908.           "entry".
  5909.  
  5910.    SEE ALSO
  5911.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _i_n_t_e_r_n_a_l_s(_3_X), _c_o_m_p_i_l_e_r(_3_X), _b_l_o_c_k_s(_3_X),
  5912.      _s_t_r_u_c_t_u_r_e_s(_3_X).
  5913.  
  5914.    NOTE
  5915.      The function list is sorted in ASCII order. The type and mode of the
  5916.      entries are indicated together with their parameter stack effect.
  5917.  
  5918.    COPYING
  5919.      Copyright (C) 1990 Mikael R.K. Patel
  5920.  
  5921.      Permission is granted to make and distribute verbatim copies of this
  5922.      manual provided the copyright notice and this permission notice are
  5923.      preserved on all copies.
  5924.  
  5925.      Permission is granted to copy and distribute modified versions of this
  5926.      manual under the conditions for verbatim copying, provided also that the
  5927.      section entitled "GNU General Public License" is included exactly as in
  5928.      the original, and provided that the entire resulting derived work is
  5929.      distributed under the terms of a permission notice identical to this
  5930.      one.
  5931.  
  5932.      Permission is granted to copy and distribute translations of this manual
  5933.      into another language, under the above conditions for modified versions,
  5934.      except that the section entitled "GNU General Public License" may be
  5935.  
  5936.  
  5937.    90
  5938.  
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.    August 21, 1990                                                 PARSER(3X)
  5945.  
  5946.  
  5947.      included in a translation approved by the author instead of in the ori-
  5948.      ginal English.
  5949.  
  5950.    AUTHOR
  5951.      Mikael R.K. Patel
  5952.      Computer Aided Design Laboratory (CADLAB)
  5953.      Department of Computer and Information Science
  5954.      Linkoping University
  5955.      S-581 83 LINKOPING
  5956.      SWEDEN
  5957.      Email: mip@ida.liu.se
  5958.  
  5959.  
  5960.  
  5961.  
  5962.  
  5963.  
  5964.  
  5965.  
  5966.  
  5967.  
  5968.  
  5969.  
  5970.  
  5971.  
  5972.  
  5973.  
  5974.  
  5975.  
  5976.  
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  
  5982.  
  5983.  
  5984.  
  5985.  
  5986.  
  5987.  
  5988.  
  5989.  
  5990.  
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.  
  5998.  
  5999.  
  6000.  
  6001.  
  6002.  
  6003.                                                                            91
  6004.  
  6005.  
  6006.  
  6007.  
  6008.  
  6009.  
  6010.    PROTOTYPES(3X)                                             August 20, 1990
  6011.  
  6012.  
  6013.  
  6014.    NAME
  6015.      prototypes - object oriented extension modeled as prototypes
  6016.  
  6017.    SYNOPSIS
  6018.      #include prototypes.f83
  6019.  
  6020.      prototypes
  6021.  
  6022.    DESCRIPTION
  6023.      Prototypes are a general form of object oriented programming which allow
  6024.      data and code sharing on any level without dividing the world into
  6025.      "classes" and "instances". A prototype may have slots and methods. Slots
  6026.      hold data values and methods are ways of answering messages. If a proto-
  6027.      type does not contain a requested slot or does not know how to answer a
  6028.      specific message it may delegate the request to another prototype
  6029.      through an inheritance relation. This library supports the definition of
  6030.      prototypes, slots, messages, and methods. It is build on top of the
  6031.      relations extensions by adding an interpreted relation, "inherits", and
  6032.      a delegation function.
  6033.  
  6034.      : .message ( message -- )
  6035.           Displays the message entry name on the current output stream.
  6036.  
  6037.      : .prototype ( prototype -- )
  6038.           Displays the prototype entry name on the current output stream. If
  6039.           the prototype does not contain an entry binding the prototype is
  6040.           displayed in the format "prototype#<address>".
  6041.  
  6042.      : .relations ( prototype -- )
  6043.           Displays the current list of relations associated with a prototype.
  6044.           The list includes all slots, methods, and the inheritance relation.
  6045.  
  6046.      : .slot ( slot -- )
  6047.           Displays the slot entry name on the current output stream.
  6048.  
  6049.      : -> ( value prototype -- ) immediate
  6050.           Used in the following form:
  6051.           <_v_a_l_u_e> <_p_r_o_t_o_t_y_p_e> -> <_s_l_o_t>
  6052.           to assign a prototype slot. If the slot is not available it is
  6053.           added to the prototypes relations. The assignment is always local
  6054.           to the prototype and does not use the inheritance chain. A proto-
  6055.           type cannot alter the value of an inherited slot without sending a
  6056.           message to the prototype who owns the slot.
  6057.  
  6058.      : inherited ( -- ) immediate compilation
  6059.           Used in the following form:
  6060.           inherited <_m_e_s_s_a_g_e>
  6061.           to send the message to the inherited prototype. The inheritance
  6062.           chain is retrieved at run-time. This allows addition dynamic bind-
  6063.           ing of messages.  This word should only be used in a method defini-
  6064.           tion.
  6065.  
  6066.      : parent ( prototype -- addr)
  6067.  
  6068.  
  6069.    92
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.    August 20, 1990                                             PROTOTYPES(3X)
  6077.  
  6078.  
  6079.           Returns the value of the inheritance relation. The value may be
  6080.           "nil".
  6081.  
  6082.      : prototype ( parent -- )
  6083.           Used in the following form:
  6084.           <_p_a_r_e_n_t> prototype <_n_a_m_e> ( -- prototype)
  6085.           to create a prototype variable. Slots and message may be associated
  6086.           with the prototype. Slots are created with the assignment operator.
  6087.           A message may be answered with a "method". The prototype will
  6088.           inherit from the <_p_a_r_e_n_t> prototype. The value "nil" should be used
  6089.           to indicate a root prototype without inheritance.
  6090.  
  6091.      : prototype>entry ( prototype -- entry)
  6092.           Returns a pointer to the vocabulary entry of the prototype. The
  6093.           value may be "nil" of a nameless prototype.
  6094.  
  6095.      vocabulary prototypes ( -- )
  6096.           The prototypes extension vocabulary. Include to the vocabulary
  6097.           search set, "context", to allow access to this library.
  6098.  
  6099.      : message ( -- )
  6100.           Used in the following form:
  6101.           message <_n_a_m_e> ( ... prototype -- ... prototype)
  6102.           to define a message type. The message will, at run-time, require
  6103.           the prototype to answer the message as parameter. A "method" for
  6104.           the message is located using the delegation function, "delegate".
  6105.           If a method is found it is applied with the prototype as the first
  6106.           parameter. If a method is not found the forward declared word
  6107.           "unknown-message" is applied with the prototype and message as
  6108.           parameters. This allows implementation of error handling as mes-
  6109.           sages and definition of proxy prototypes.
  6110.  
  6111.      : method ( prototype -- )
  6112.           Used in the following form:
  6113.           <_p_r_o_t_o_t_y_p_e> method <_m_e_s_s_a_g_e> ( ... prototype -- ...) ... ;
  6114.           to define a prototype method of a message. The method is added to
  6115.           the prototypes relations. The method becomes the new method if a
  6116.           method already exists for the message. The method will always
  6117.           receive the prototype, self, as the first parameter. The method
  6118.           acts as a normal colon definition but it may not contain the fol-
  6119.           lowing words; "exception>", "recurse", and "tail-recurse", as these
  6120.           require an entry binding.
  6121.  
  6122.      : new-prototype ( parent -- prototype)
  6123.           Returns a new nameless prototype with the given parent. The parent
  6124.           value may be "nil" for a root prototype.
  6125.  
  6126.      : slot ( -- )
  6127.           Used in the following form:
  6128.           slot <_n_a_m_e> ( prototype -- value)
  6129.           to create a slot name. The slot, when used, will require a proto-
  6130.           type as parameter and will return the current value. If the slot
  6131.           cannot be found after delegation the forward declared word
  6132.           "unknown-slot" is applied with the prototype and slot as
  6133.  
  6134.  
  6135.                                                                            93
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.    PROTOTYPES(3X)                                             August 20, 1990
  6143.  
  6144.  
  6145.           parameters. This allows error handling as a message or as a colon
  6146.           definitions. A slot may be assigned with the prefix operator "->".
  6147.  
  6148.      : this-prototype ( -- prototype)
  6149.           Returns the prototype address. Should be used after the word "pro-
  6150.           totype" as it requires the last entry to be a prototype definition.
  6151.  
  6152.      forward unknown-message ( message prototype -- )
  6153.           This word is called when the delegation function cannot locate a
  6154.           method for the message for the prototype. This word may be defined
  6155.           as a message or as a colon definition.
  6156.  
  6157.      forward unknown-slot ( slot prototype -- )
  6158.           This word is called when the delegation function cannot locate a
  6159.           slot for the prototype. This word may be defined as a message or as
  6160.           a colon definition.
  6161.  
  6162.    INTERNALS
  6163.      Private definitions in the _p_r_o_t_o_t_y_p_e_s vocabulary;
  6164.  
  6165.      : (inherited) ( prototype message -- )
  6166.           Run-time action for the word "inherited". Delegates the message to
  6167.           the parent prototype instead of searching at the prototype itself.
  6168.  
  6169.    true]) private
  6170.      : delegate ( relation prototype -- [relation prototype false] or [value
  6171.           Primitive lookup function. Used to locate slots and methods for a
  6172.           prototype.  Extends the relations lookup function "?get-relation"
  6173.           so that relations may be located along the prototypes inheritance
  6174.           chain.
  6175.  
  6176.      item inherits ( -- relation) private
  6177.           The predefined inheritance item. Used by the delegation function,
  6178.           "delegate", and other dependent functions, e.g., "slot" and "mes-
  6179.           sage".
  6180.  
  6181.      variable the-prototype ( -- addr) private
  6182.           Variable containing the method prototype. Bound by the word
  6183.           "method" and used by the word "inherit" to access the current
  6184.           definition prototype.
  6185.  
  6186.    SEE ALSO
  6187.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _r_e_l_a_t_i_o_n_s(_3_X).
  6188.  
  6189.    NOTE
  6190.      The function list is sorted in ASCII order. The type and mode of the
  6191.      entries are indicated together with their parameter stack effect.
  6192.  
  6193.    WARNING
  6194.      This library contains forward declared words which should be supplied.
  6195.      Check that your definitions vocabulary comes before the "prototypes"
  6196.      vocabulary when defining these words.
  6197.  
  6198.  
  6199.  
  6200.  
  6201.    94
  6202.  
  6203.  
  6204.  
  6205.  
  6206.  
  6207.  
  6208.    August 20, 1990                                             PROTOTYPES(3X)
  6209.  
  6210.  
  6211.    COPYING
  6212.      Copyright (C) 1990 Mikael R.K. Patel
  6213.  
  6214.      Permission is granted to make and distribute verbatim copies of this
  6215.      manual provided the copyright notice and this permission notice are
  6216.      preserved on all copies.
  6217.  
  6218.      Permission is granted to copy and distribute modified versions of this
  6219.      manual under the conditions for verbatim copying, provided also that the
  6220.      section entitled "GNU General Public License" is included exactly as in
  6221.      the original, and provided that the entire resulting derived work is
  6222.      distributed under the terms of a permission notice identical to this
  6223.      one.
  6224.  
  6225.      Permission is granted to copy and distribute translations of this manual
  6226.      into another language, under the above conditions for modified versions,
  6227.      except that the section entitled "GNU General Public License" may be
  6228.      included in a translation approved by the author instead of in the ori-
  6229.      ginal English.
  6230.  
  6231.    AUTHOR
  6232.      Mikael R.K. Patel
  6233.      Computer Aided Design Laboratory (CADLAB)
  6234.      Department of Computer and Information Science
  6235.      Linkoping University
  6236.      S-581 83 LINKOPING
  6237.      SWEDEN
  6238.      Email: mip@ida.liu.se
  6239.  
  6240.  
  6241.  
  6242.  
  6243.  
  6244.  
  6245.  
  6246.  
  6247.  
  6248.  
  6249.  
  6250.  
  6251.  
  6252.  
  6253.  
  6254.  
  6255.  
  6256.  
  6257.  
  6258.  
  6259.  
  6260.  
  6261.  
  6262.  
  6263.  
  6264.  
  6265.  
  6266.  
  6267.                                                                            95
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.    QUEUES(3X)                                                  August 6, 1990
  6275.  
  6276.  
  6277.  
  6278.    NAME
  6279.      queues - tile kernel double linked list extensions
  6280.  
  6281.    SYNOPSIS
  6282.      #include queues.f83
  6283.  
  6284.      queues
  6285.  
  6286.    DESCRIPTION
  6287.      The _t_i_l_e forth kernel word set for support of double linked circular
  6288.      lists.  Used by the kernel to maintain the run-time queue of tasks for
  6289.      the multi-tasking extension.
  6290.  
  6291.      : .queue ( queue -- )
  6292.           Displays information about a queue header or item in the format:
  6293.           queue# <_q_u_e_u_e-_p_o_i_n_t_e_r> succ: <_s_u_c_c-_p_o_i_n_t_e_r> pred: <_p_r_e_d-_p_o_i_n_t_e_r>
  6294.  
  6295.      code ?empty-queue ( queue -- bool)
  6296.           Returns "true" if the queue is empty else "false". Successor
  6297.           pointer points to the queue itself. This definition is also avail-
  6298.           able as forth code for portability to other environments.
  6299.  
  6300.      : ?map-queue ( queue block[item -- bool] -- )
  6301.           Used in the following form:
  6302.           <_q_u_e_u_e> <_c_o_n_d_i_t_i_o_n_a_l-_b_l_o_c_k> ?map-queue
  6303.           to perform a block of code on each element of the queue until the
  6304.           block returns "true".
  6305.  
  6306.      : ?member-queue ( item queue -- bool)
  6307.           Search for "item" in "queue". If found returns "true" else "false".
  6308.  
  6309.      struct.type QUEUE ( -- )
  6310.           Structure definition of double linked list. Used as follows to
  6311.           create a new queue header instance:
  6312.           new-struct QUEUE ( -- queue)
  6313.           A named queue header may be created with:
  6314.           QUEUE <_q_u_e_u_e-_n_a_m_e> ( -- queue)
  6315.           Contains two private fields, "+succ" and "+pred".
  6316.  
  6317.      code dequeue ( item -- )
  6318.           Removes "item" from any queue. Observe this function does not
  6319.           require knowledge about which queue "item" is a member of.  This
  6320.           definition is also available as a colon definition for portability
  6321.           of other environments.
  6322.  
  6323.      code enqueue ( item queue -- )
  6324.           Inserts "item" into "queue" as the new predecessor element. If the
  6325.           "queue" parameter is a queue header "item" is inserted last into
  6326.           the queue. "item" must be a pointer to a "QUEUE" field of a struc-
  6327.           ture or a sub-structure of "QUEUE".  This definition is also avail-
  6328.           able as a colon definition for portability of other environments.
  6329.  
  6330.      : map-queue ( queue block[item -- ] -- )
  6331.  
  6332.  
  6333.    96
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.    August 6, 1990                                                  QUEUES(3X)
  6341.  
  6342.  
  6343.           Used in the following form:
  6344.           <_q_u_e_u_e> <_b_l_o_c_k> map
  6345.           Calls the parameter code "block" on each item in the queue.
  6346.  
  6347.      vocabulary queues ( -- )
  6348.           Vocabulary containing double linked circular list extensions.
  6349.           Include into the vocabulary search structure, "context", to gain
  6350.           access to these extensions.
  6351.  
  6352.      : size-queue ( queue -- num)
  6353.           Returns the length of a queue. The queue head is counted. Returns a
  6354.           integer larger than zero.
  6355.  
  6356.      : succ ( queue1 -- queue2)
  6357.           Returns pointer to successor queue item.
  6358.  
  6359.      : pred ( queue1 -- queue2)
  6360.           Returns pointer to predecessor queue item.
  6361.  
  6362.    INTERNALS
  6363.      Private definitions in the _q_u_e_u_e_s vocabulary;
  6364.  
  6365.      ptr +succ ( queue -- addr) private
  6366.           Field of the structure type "QUEUE". Modifiers a queue pointer to
  6367.           access successor pointer in queue structure.
  6368.  
  6369.      ptr +pred ( queue -- addr) private
  6370.           Field of the structure type "QUEUE". Modifiers a queue pointer to
  6371.           access predecessor pointer in queue structure.
  6372.  
  6373.    SEE ALSO
  6374.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X).
  6375.  
  6376.    NOTE
  6377.      The function list is sorted in ASCII order. The type and mode of the
  6378.      entries are indicated together with their parameter stack effect.
  6379.  
  6380.    COPYING
  6381.      Copyright (C) 1990 Mikael R.K. Patel
  6382.  
  6383.      Permission is granted to make and distribute verbatim copies of this
  6384.      manual provided the copyright notice and this permission notice are
  6385.      preserved on all copies.
  6386.  
  6387.      Permission is granted to copy and distribute modified versions of this
  6388.      manual under the conditions for verbatim copying, provided also that the
  6389.      section entitled "GNU General Public License" is included exactly as in
  6390.      the original, and provided that the entire resulting derived work is
  6391.      distributed under the terms of a permission notice identical to this
  6392.      one.
  6393.  
  6394.      Permission is granted to copy and distribute translations of this manual
  6395.      into another language, under the above conditions for modified versions,
  6396.      except that the section entitled "GNU General Public License" may be
  6397.  
  6398.  
  6399.                                                                            97
  6400.  
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.    QUEUES(3X)                                                  August 6, 1990
  6407.  
  6408.  
  6409.      included in a translation approved by the author instead of in the ori-
  6410.      ginal English.
  6411.  
  6412.    AUTHOR
  6413.      Mikael R.K. Patel
  6414.      Computer Aided Design Laboratory (CADLAB)
  6415.      Department of Computer and Information Science
  6416.      Linkoping University
  6417.      S-581 83 LINKOPING
  6418.      SWEDEN
  6419.      Email: mip@ida.liu.se
  6420.  
  6421.  
  6422.  
  6423.  
  6424.  
  6425.  
  6426.  
  6427.  
  6428.  
  6429.  
  6430.  
  6431.  
  6432.  
  6433.  
  6434.  
  6435.  
  6436.  
  6437.  
  6438.  
  6439.  
  6440.  
  6441.  
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.  
  6451.  
  6452.  
  6453.  
  6454.  
  6455.  
  6456.  
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.  
  6463.  
  6464.  
  6465.    98
  6466.  
  6467.  
  6468.  
  6469.  
  6470.  
  6471.  
  6472.    August 6, 1990                                                  RANGES(3X)
  6473.  
  6474.  
  6475.  
  6476.    NAME
  6477.      ranges - integer range functions library
  6478.  
  6479.    SYNOPSIS
  6480.      #include ranges.f83
  6481.  
  6482.      ranges
  6483.  
  6484.    DESCRIPTION
  6485.      The _t_i_l_e forth integer range library. Allows definition and manipulation
  6486.      of ranges of integers. Defines a recognition function so that standard
  6487.      range notation may be used, i.e., [<from>..<to>], where <from> and <to>
  6488.      are integer values.
  6489.  
  6490.      struct.type RANGE ( from to -- )
  6491.           The range defined as a structure type thus structure operations are
  6492.           allowed (e.g. sizeof) and access of the interval range numbers.
  6493.           May be used to create range variables or fields in "structures".
  6494.           The "RANGE" variable may be accessed using the double number memory
  6495.           access functions; "2@", and "2!". The structure type contains two
  6496.           private fields, "+from" and "+to".
  6497.  
  6498.      : range ( from to -- )
  6499.           Used in the following form to create a range constant:
  6500.           <_f_r_o_m> <_t_o> range <_r_a_n_g_e-_n_a_m_e> ( -- from to)
  6501.           When the range constant is used it will produce the values.  Any
  6502.           double variable may used as an integer range if the values are in
  6503.           the right order, "from".."to", and may be accessed and manipulated
  6504.           with the double number stack and memory access functions.
  6505.  
  6506.      vocabulary ranges ( -- )
  6507.           Integer range extensions vocabulary. Include into the vocabulary
  6508.           search structure, "context", to allow access to these extensions.
  6509.  
  6510.      : ?intersection-range ( from1 to1 from2 to2 -- bool)
  6511.           Returns "true" if there exists an intersection range between the
  6512.           two ranges defined by "from1".."to1" and "from2".."to2" else
  6513.           "false".
  6514.  
  6515.      : ?map-range ( from to block[index -- bool] -- )
  6516.           Used in the following form:
  6517.           <_r_a_n_g_e> <_c_o_n_d_i_t_i_o_n_a_l-_b_l_o_c_k> ?map
  6518.           Conditional map function on a range. The block is called for each
  6519.           value of the range starting with "from" and ending with "to" until
  6520.           the block returns "true". The block receives the index as a parame-
  6521.           ter and should return a boolean value.
  6522.  
  6523.      : ?member-range ( x from to -- bool)
  6524.           Returns "true" if the value is within the range defined by "from"
  6525.           and "to" else "false".
  6526.  
  6527.      : ?range ( str -- [from to true] or [str false]) recognizer
  6528.           The integer range recognition function. Is called automatically by
  6529.  
  6530.  
  6531.                                                                            99
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.    RANGES(3X)                                                  August 6, 1990
  6539.  
  6540.  
  6541.           "interpret" when a literal is encountered and the "ranges" vocabu-
  6542.           lary is member of the search chain. The recognizer function will
  6543.           return "true" if the parameter string is of the format: [ <_f_r_o_m> ..
  6544.           <_t_o> ] and the relationship between the numbers is correct, i.e.,
  6545.           <_t_o> is greater or equal to <_f_r_o_m>.
  6546.  
  6547.      : intersection-range ( from1 to1 from2 to2 -- from3 to3)
  6548.           Given two ranges defined by "from1".."to1" and "from2".."to2"
  6549.           returns their intersection. This function does not check if an
  6550.           intersection exists. This may be done with the word
  6551.           "?intersection-range".
  6552.  
  6553.      : map-range ( from to block[index -- ] -- )
  6554.           Used in the following form:
  6555.           <_r_a_n_g_e> <_b_l_o_c_k> map-range
  6556.           Map function on a range defined by "from" and "to". The block is
  6557.           called for each value of the range starting with "from" and ending
  6558.           with "to". The block receives the index as a parameter.
  6559.  
  6560.      : size-range ( from to -- num)
  6561.           Returns the size of the range by calculating "to" - "from" + 1.
  6562.  
  6563.    INTERNALS
  6564.      Private definitions in the _r_a_n_g_e_s vocabulary;
  6565.  
  6566.      long +from ( range -- addr) private
  6567.           Returns address to "from" value of a "RANGE" structure.
  6568.  
  6569.      long +to ( range -- addr) private
  6570.           Returns address to "to" value of a "RANGE" structure.
  6571.  
  6572.    SEE ALSO
  6573.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X).
  6574.  
  6575.    EXAMPLES
  6576.      An example showing how to used the integer ranges extensions:
  6577.  
  6578.           #include blocks.f83
  6579.           #include ranges.f83
  6580.  
  6581.           blocks ranges
  6582.  
  6583.           [0..15] range small-numbers
  6584.           small-number block[ ( index -- ) . ]; map-range cr
  6585.  
  6586.           10 [-128..127] ?member-range . cr
  6587.  
  6588.    NOTE
  6589.      The function list is sorted in ASCII order. The type and mode of the
  6590.      entries are indicated together with their parameter stack effect.
  6591.  
  6592.  
  6593.  
  6594.  
  6595.  
  6596.  
  6597.    100
  6598.  
  6599.  
  6600.  
  6601.  
  6602.  
  6603.  
  6604.    August 6, 1990                                                  RANGES(3X)
  6605.  
  6606.  
  6607.    COPYING
  6608.      Copyright (C) 1990 Mikael R.K. Patel
  6609.  
  6610.      Permission is granted to make and distribute verbatim copies of this
  6611.      manual provided the copyright notice and this permission notice are
  6612.      preserved on all copies.
  6613.  
  6614.      Permission is granted to copy and distribute modified versions of this
  6615.      manual under the conditions for verbatim copying, provided also that the
  6616.      section entitled "GNU General Public License" is included exactly as in
  6617.      the original, and provided that the entire resulting derived work is
  6618.      distributed under the terms of a permission notice identical to this
  6619.      one.
  6620.  
  6621.      Permission is granted to copy and distribute translations of this manual
  6622.      into another language, under the above conditions for modified versions,
  6623.      except that the section entitled "GNU General Public License" may be
  6624.      included in a translation approved by the author instead of in the ori-
  6625.      ginal English.
  6626.  
  6627.    AUTHOR
  6628.      Mikael R.K. Patel
  6629.      Computer Aided Design Laboratory (CADLAB)
  6630.      Department of Computer and Information Science
  6631.      Linkoping University
  6632.      S-581 83 LINKOPING
  6633.      SWEDEN
  6634.      Email: mip@ida.liu.se
  6635.  
  6636.  
  6637.  
  6638.  
  6639.  
  6640.  
  6641.  
  6642.  
  6643.  
  6644.  
  6645.  
  6646.  
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.  
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.  
  6661.  
  6662.  
  6663.                                                                           101
  6664.  
  6665.  
  6666.  
  6667.  
  6668.  
  6669.  
  6670.    RATIONALS(3X)                                               August 6, 1990
  6671.  
  6672.  
  6673.  
  6674.    NAME
  6675.      rationals - rational number library
  6676.  
  6677.    SYNOPSIS
  6678.      #include rationals.f83
  6679.  
  6680.      rationals
  6681.  
  6682.    DESCRIPTION
  6683.      The _t_i_l_e forth rational number library. Allows definition and manipula-
  6684.      tion of rational numbers. Defines a recognition function so that stan-
  6685.      dard rational notation may be used, i.e., <num>/<denom>, where <num> and
  6686.      <denom> are integer values. The rational number system also includes the
  6687.      numbers "undefined" and "infinity". All rational number functions nor-
  6688.      malize their results to maintain as small numbers as possible.  Overflow
  6689.      conditions are not checked. Rational numbers are maintained on the stack
  6690.      as an integer number pair. No extra memory is required for arithmetic
  6691.      operations. Double number stack words may be used to mainipulate the
  6692.      rational number.
  6693.  
  6694.      rational -infinity ( -- num denom)
  6695.           The rational number constant for minus infinity.
  6696.  
  6697.      : 1/r ( num1 denom1 -- num2 denom2)
  6698.           Returns the result of dividing one by the rational number,
  6699.           "num1"/"denom1".
  6700.  
  6701.      : ?r< ( num1 denom1 num2 denom2 -- bool)
  6702.           Returns "true" if the rational number, "num1"/"denom1", is arith-
  6703.           metic less than the rational number, "num2"/"denom2" else "false".
  6704.  
  6705.      : ?r= ( num1 denom1 num2 denom2 -- bool)
  6706.           Returns "true" if the rational number, "num1"/"denom1", is arith-
  6707.           metic equal than the rational number, "num2"/"denom2" else "false".
  6708.  
  6709.      : ?r> ( num1 denom1 num2 denom2 -- bool)
  6710.           Returns "true" if the rational number, "num1"/"denom1", is arith-
  6711.           metic greater than the rational number, "num2"/"denom2" else
  6712.           "false".
  6713.  
  6714.      : ?rational ( str -- [num denom true] or [str false]) recognizer
  6715.           The rational number vocabulary literal recognizer function. Will
  6716.           determinate if the string is a rational number using the syntax
  6717.           "<num>/<denom>", where <num> is an integer and <denom> a positive
  6718.           number. The rational number is normalized using the function,
  6719.           "rnormalize", and the value return with the flag "true". If the
  6720.           string is not a rational number the string is returned with the
  6721.           flag "false"
  6722.  
  6723.      struct.type RATIONAL ( -- )
  6724.           Used in the following form:
  6725.           RATIONAL <_n_a_m_e> ( -- rational)
  6726.           to create a rational variable. The variable should be accessed with
  6727.  
  6728.  
  6729.    102
  6730.  
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.    August 6, 1990                                               RATIONALS(3X)
  6737.  
  6738.  
  6739.           the double number memory access functions, "2@" and "2!". The
  6740.           structure type "RATIONAL" contains two private fields; "+num" and
  6741.           "+denom".
  6742.  
  6743.      : i>r ( x -- num denom)
  6744.           Converts the integer value to a rational number.
  6745.  
  6746.      rational infinity ( -- num denom)
  6747.           Returns the value for the rational number for infinity.
  6748.  
  6749.      : r* ( num1 denom1 num2 denom2 -- num3 denom3)
  6750.           Returns the product of the two rational numbers, "num1"/"denom1"
  6751.           and "num2"/"denom2". The result is always normalized.
  6752.  
  6753.      : r+ ( num1 denom1 num2 denom2 -- num3 denom3)
  6754.           Returns the sum of the two rational numbers, "num1"/"denom1" and
  6755.           "num2"/"denom2". The result is always normalized.
  6756.  
  6757.      : r- ( num1 denom1 num2 denom2 -- num3 denom3)
  6758.           Returns the difference of the two rational numbers, "num1"/"denom1"
  6759.           and "num2"/"denom2". The result is always normalized.
  6760.  
  6761.      : r. ( num denom -- )
  6762.           Displays the rational number in the standard format, "num"/"denom".
  6763.           If the value is zero or infinity these strings are displayed.
  6764.  
  6765.      : r/ ( num1 denom1 num2 denom2 -- num3 denom3)
  6766.           Returns the quotient of the two rational numbers, "num1"/"denom1"
  6767.           and "num2"/"denom2". The result is always normalized.
  6768.  
  6769.      : r>i ( num denom -- x)
  6770.           Converts the rational number to an integer. The result is trun-
  6771.           cated.
  6772.  
  6773.      : rational ( num denom -- )
  6774.           Used in the following form:
  6775.           <_n_u_m> <_d_e_n_o_m> rational <_n_a_m_e> ( -- num denom)
  6776.           to create a rational number constant. The rational number is
  6777.           restored when the entry is used.
  6778.  
  6779.      vocabulary rationals ( -- )
  6780.           The rational number extension vocabulary. Include into the vocabu-
  6781.           lary search set, "context", to allow access of this library.
  6782.  
  6783.      : rnegate ( num1 denom1 -- num2 denom2)
  6784.           Returns the result of negating the rational number,
  6785.           "num1"/"denom1".
  6786.  
  6787.      : rnormalize ( num1 denom1 -- num2 denom2)
  6788.           Normalizes the rational number, "num1"/"denom1", towards zero using
  6789.           greatest common divisor.
  6790.  
  6791.      rational undefined ( -- num denom)
  6792.           The rational number constant for undefined.
  6793.  
  6794.  
  6795.                                                                           103
  6796.  
  6797.  
  6798.  
  6799.  
  6800.  
  6801.  
  6802.    RATIONALS(3X)                                               August 6, 1990
  6803.  
  6804.  
  6805.      rational zero ( -- num denom)
  6806.           The rational number constant for zero. The value "0/0" may also be
  6807.           used for zero.
  6808.  
  6809.    INTERNALS
  6810.      Private definitions in the _r_a_t_i_o_n_a_l_s vocabulary;
  6811.  
  6812.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X).
  6813.  
  6814.    NOTE
  6815.      The function list is sorted in ASCII order. The type and mode of the
  6816.      entries are indicated together with their parameter stack effect.
  6817.  
  6818.    COPYING
  6819.      Copyright (C) 1990 Mikael R.K. Patel
  6820.  
  6821.      Permission is granted to make and distribute verbatim copies of this
  6822.      manual provided the copyright notice and this permission notice are
  6823.      preserved on all copies.
  6824.  
  6825.      Permission is granted to copy and distribute modified versions of this
  6826.      manual under the conditions for verbatim copying, provided also that the
  6827.      section entitled "GNU General Public License" is included exactly as in
  6828.      the original, and provided that the entire resulting derived work is
  6829.      distributed under the terms of a permission notice identical to this
  6830.      one.
  6831.  
  6832.      Permission is granted to copy and distribute translations of this manual
  6833.      into another language, under the above conditions for modified versions,
  6834.      except that the section entitled "GNU General Public License" may be
  6835.      included in a translation approved by the author instead of in the ori-
  6836.      ginal English.
  6837.  
  6838.    AUTHOR
  6839.      Mikael R.K. Patel
  6840.      Computer Aided Design Laboratory (CADLAB)
  6841.      Department of Computer and Information Science
  6842.      Linkoping University
  6843.      S-581 83 LINKOPING
  6844.      SWEDEN
  6845.      Email: mip@ida.liu.se
  6846.  
  6847.  
  6848.  
  6849.  
  6850.  
  6851.  
  6852.  
  6853.  
  6854.  
  6855.  
  6856.  
  6857.  
  6858.  
  6859.  
  6860.  
  6861.    104
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.    August 20, 1990                                              RELATIONS(3X)
  6869.  
  6870.  
  6871.  
  6872.    NAME
  6873.      relations - experimental library for data modeling as relations
  6874.  
  6875.    SYNOPSIS
  6876.      #include relations.f83
  6877.  
  6878.      relations
  6879.  
  6880.    DESCRIPTION
  6881.      This library allow data represent in one of the most general forms of
  6882.      data modeling with unrestricted data and code sharing. Data is described
  6883.      as a relations, a triple: (item X relation X value). The library sup-
  6884.      ports some of the common iterators over the relation set.  Depending on
  6885.      how the attribute is used the search for the attribute-value may be
  6886.      minimized. This implementation uses association lists where the
  6887.      attribute-values is associated with the item. The items may act as both
  6888.      node with relations and as names of relations. The interface to this
  6889.      library is choosen so that internal implementation details are visible.
  6890.      This allows the library to be implemented in other forms such as hash-
  6891.      tables, mapping tables, trees, etc.
  6892.  
  6893.      : .item ( item -- )
  6894.           Displays the item entry name to the current output stream. If the
  6895.           item is not bound to a entry the following form is used:
  6896.           "item#<address>".
  6897.  
  6898.      : .items ( -- )
  6899.           Displays the current list of items to the current output stream.
  6900.  
  6901.      : .relations ( item -- )
  6902.           Displays the current list of relations for the item on the current
  6903.           output stream.
  6904.  
  6905.      : .values ( item -- )
  6906.           Displays the current list of attribute-value pairs associated with
  6907.           the item on the current output stream.
  6908.  
  6909.      : ?avail-relations ( relation item -- bool)
  6910.           Returns "true" if the relation is available else "false".
  6911.  
  6912.      : ?get-relation ( relation item --
  6913.            [relation item false] or [value true])
  6914.           Returns the value of the relation of the item and "true" if found
  6915.           else this function will return the relation and the item and
  6916.           "false".
  6917.  
  6918.      : ?is-relation ( value relation item -- bool)
  6919.           Returns "true" if the relation has the value given else "false".
  6920.           The values are tested with arithmetric equal.
  6921.  
  6922.      struct.type ITEM ( -- )
  6923.           Structure type for an item. Used by "item" to create the internals
  6924.           of an item. The item is used both for relational data storage and
  6925.  
  6926.  
  6927.                                                                           105
  6928.  
  6929.  
  6930.  
  6931.  
  6932.  
  6933.  
  6934.    RELATIONS(3X)                                              August 20, 1990
  6935.  
  6936.  
  6937.           as an attribute. The words "new-item" and "item" should be used to
  6938.           create "item" words. Contains three private structure fields;
  6939.           "+next-item", "+entry", and "+associations".
  6940.  
  6941.      : item ( -- )
  6942.           Used in the following form:
  6943.           item <_n_a_m_e> ( -- item)
  6944.           to create an item entry. The <_n_a_m_e> will return the address of the
  6945.           item when used. The item may be used to associate value with and
  6946.           may also be used as a relation.
  6947.  
  6948.      variable items ( -- )
  6949.           Global variable in the "relations" extension holding the list of
  6950.           defined items (with the word "item"). The latest defined item
  6951.           occurs first in the list. This variable may be accessed and changed
  6952.           to create item sets.
  6953.  
  6954.      : item>entry ( item -- entry)
  6955.           Returns the entry address of the item. This value may be "nil"
  6956.           depending on how the item was created.
  6957.  
  6958.      : get-relation ( relation item -- value)
  6959.           Returns the value of the relation of the item. The value is assumed
  6960.           to exist. If the relation is not found this function will fail and
  6961.           a memory access signal is generated.
  6962.  
  6963.      : map-item ( item block[value relation -- ] -- )
  6964.           Used in the following form:
  6965.           <_i_t_e_m> block[ ( value relation -- ) ... ]; map-item
  6966.           to apply a block to each relation and value pair associated with an
  6967.           item.  The block will receive the relation and its value as parame-
  6968.           ters.
  6969.  
  6970.      : map-items ( block[item -- ] -- )
  6971.           Used in the following form:
  6972.           block[ ( item -- ) ... ]; map-items
  6973.           to apply a block to each item in the relation set. The block will
  6974.           receive the item as a parameter. May be used to iterate over the
  6975.           item set and extract all items with a certain relation.
  6976.  
  6977.      : map-relation ( relation block[value item -- ] -- )
  6978.           Used in the following form:
  6979.           <_r_e_l_a_t_i_o_n> block[ ( value item -- ) ... ]; map-relation
  6980.           to apply a block to each item with the given relation. The block
  6981.           will receive the item and the relation value as parameters. The
  6982.           relation may be an item or a number, pointer etc. The typing of the
  6983.           value is up to the application but may also be stored as a rela-
  6984.           tion.
  6985.  
  6986.      : new-item ( entry -- item)
  6987.           Returns a new item with the entry binding. The new item will become
  6988.           nameless if the entry is "nil".
  6989.  
  6990.      : put-relation ( value relation item -- )
  6991.  
  6992.  
  6993.    106
  6994.  
  6995.  
  6996.  
  6997.  
  6998.  
  6999.  
  7000.    August 20, 1990                                              RELATIONS(3X)
  7001.  
  7002.  
  7003.           Adds the relation and value to the items associations. If the rela-
  7004.           tion is available defined the new value is assigned. If the rela-
  7005.           tion is not available a new relation-value pair is created and
  7006.           appended to the associations.
  7007.  
  7008.      vocabulary relations ( -- )
  7009.           The relations library vocabulary. Include into the vocabulary
  7010.           search set, "context", to allow access to these extensions.
  7011.  
  7012.      : remove-relation ( relation item -- )
  7013.           Removes the relation from the items associations. If the relation
  7014.           is not available no operation is performed.
  7015.  
  7016.    INTERNALS
  7017.      Private definitions in the _r_e_l_a_t_i_o_n_s vocabulary;
  7018.  
  7019.      ptr +associations ( item -- addr) private
  7020.           Structure access field of "ITEM" to the list of associations. The
  7021.           value is a pointer to an "ASSOCIATION" structure.
  7022.  
  7023.      ptr +entry ( item -- addr) private
  7024.           Structure access field of "ITEM" to the entry. Used to access the
  7025.           name field of the item.
  7026.  
  7027.      ptr +next-association ( association -- addr) private
  7028.           Structure access field of "ASSOCIATION" to the next association in
  7029.           the list of associations. The value is a pointer to an "ASSOCIA-
  7030.           TION" structure.
  7031.  
  7032.      ptr +next-item ( item -- addr) private
  7033.           Structure access field of "ITEM" to the list of item entries. The
  7034.           value is a pointer to the next "ITEM" structure in the list of
  7035.           items.
  7036.  
  7037.      ptr +relation ( association -- addr) private
  7038.           Structure access field of "ASSOCIATION" to relation of the associa-
  7039.           tion. The value should be a "ITEM" pointer.
  7040.  
  7041.      ptr +value ( association -- addr) private
  7042.           Structure access field of "ASSOCIATION" to value of a relation. The
  7043.           value is store in a "cell".
  7044.  
  7045.      struct.type ASSOCIATION ( -- ) private
  7046.           Structure type for an association. The association is a triple list
  7047.           element with three private fields; "+next-association", "+rela-
  7048.           tion", and "+value".
  7049.  
  7050.      : associate ( relation association -- addr) private
  7051.           Primitive lookup function used by "get-relation", "?get-relation"
  7052.           and "put-relation" to locate an "ASSOCIATION" in the association
  7053.           list. Returns the address of the value if the relation is found. If
  7054.           the relation is not found "nil" is returned.
  7055.  
  7056.  
  7057.  
  7058.  
  7059.                                                                           107
  7060.  
  7061.  
  7062.  
  7063.  
  7064.  
  7065.  
  7066.    RELATIONS(3X)                                              August 20, 1990
  7067.  
  7068.  
  7069.    SEE ALSO
  7070.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X).
  7071.  
  7072.    NOTE
  7073.      The function list is sorted in ASCII order. The type and mode of the
  7074.      entries are indicated together with their parameter stack effect.
  7075.  
  7076.    COPYING
  7077.      Copyright (C) 1990 Mikael R.K. Patel
  7078.  
  7079.      Permission is granted to make and distribute verbatim copies of this
  7080.      manual provided the copyright notice and this permission notice are
  7081.      preserved on all copies.
  7082.  
  7083.      Permission is granted to copy and distribute modified versions of this
  7084.      manual under the conditions for verbatim copying, provided also that the
  7085.      section entitled "GNU General Public License" is included exactly as in
  7086.      the original, and provided that the entire resulting derived work is
  7087.      distributed under the terms of a permission notice identical to this
  7088.      one.
  7089.  
  7090.      Permission is granted to copy and distribute translations of this manual
  7091.      into another language, under the above conditions for modified versions,
  7092.      except that the section entitled "GNU General Public License" may be
  7093.      included in a translation approved by the author instead of in the ori-
  7094.      ginal English.
  7095.  
  7096.    AUTHOR
  7097.      Mikael R.K. Patel
  7098.      Computer Aided Design Laboratory (CADLAB)
  7099.      Department of Computer and Information Science
  7100.      Linkoping University
  7101.      S-581 83 LINKOPING
  7102.      SWEDEN
  7103.      Email: mip@ida.liu.se
  7104.  
  7105.  
  7106.  
  7107.  
  7108.  
  7109.  
  7110.  
  7111.  
  7112.  
  7113.  
  7114.  
  7115.  
  7116.  
  7117.  
  7118.  
  7119.  
  7120.  
  7121.  
  7122.  
  7123.  
  7124.  
  7125.    108
  7126.  
  7127.  
  7128.  
  7129.  
  7130.  
  7131.  
  7132.    August 7, 1990                                                    SETS(3X)
  7133.  
  7134.  
  7135.  
  7136.    NAME
  7137.      sets - vector represented sets definitions
  7138.  
  7139.    SYNOPSIS
  7140.      #include sets.f83
  7141.  
  7142.      sets
  7143.  
  7144.    DESCRIPTION
  7145.      Library for sets represented as vectors. The set is a terminated by a
  7146.      "nil" pointer. This set representation is mainly used for small sets of
  7147.      entry pointer and other non-zero values. "nil" and zero cannot be
  7148.      members of a set.  The vocabulary search chain is represented as a set.
  7149.  
  7150.      : .set ( set -- )
  7151.           Assuming that the set contains elements that are vocabulary entries
  7152.           this function will display the set in normal set notation:
  7153.           { <_e_n_t_r_i_e_s> }
  7154.           The format is equal to the input notation constant sets.
  7155.  
  7156.      : ?empty-set ( set -- bool)
  7157.           Returns "true" if the set is empty else "false".
  7158.  
  7159.      : ?map-set ( set block[element -- bool] -- )
  7160.           Conditional set iterator. Calls the conditional block on each ele-
  7161.           ment in the set while the block returns "false". The iterator is
  7162.           terminated if the block returns "true" or if the block is empty.
  7163.           The conditional block will receive the element as a parameter and
  7164.           should return a boolean flag.
  7165.  
  7166.      : ?member-set ( element set -- bool)
  7167.           Returns "true" if the element is a member of the set else "false".
  7168.  
  7169.      : append-set ( element set -- )
  7170.           The element is appended to the set. If the element is already a
  7171.           member of the set no operation is performed. An element cannot
  7172.           occur more than once in a set.
  7173.  
  7174.      : apply-set ( set -- )
  7175.           Assuming all elements of the set are entry pointers this words will
  7176.           "execute" all elements once.
  7177.  
  7178.      : empty-set ( set -- )
  7179.           Assign the set as the empty set.
  7180.  
  7181.      : intersection-set ( set1 set2 -- )
  7182.           Remove elements in both "set1" and "set2" from "set2". "set2"
  7183.           becomes the intersection of the sets.
  7184.  
  7185.      : map-set ( set block[element -- ] -- )
  7186.           Set iterator function. Call the block on each element in the set.
  7187.           The block will receive the element as a parameter.
  7188.  
  7189.  
  7190.  
  7191.                                                                           109
  7192.  
  7193.  
  7194.  
  7195.  
  7196.  
  7197.  
  7198.    SETS(3X)                                                    August 7, 1990
  7199.  
  7200.  
  7201.      : remove-set ( element set -- )
  7202.           Remove the element from the set. If the element is not a member of
  7203.           the set no operation is taken.
  7204.  
  7205.      : set ( size -- )
  7206.           Used in the following form:
  7207.           <_s_i_z_e> set <_s_e_t-_n_a_m_e> ( -- set)
  7208.           to create of set for "size"-1 elements. Each element is "cell"
  7209.           bytes and may contain a number or pointer.
  7210.  
  7211.      vocabulary sets ( -- )
  7212.           The vector represented set extension vocabulary. Include into the
  7213.           vocabulary search set, "context", to allow access of this library.
  7214.  
  7215.      : size-set ( set -- num)
  7216.           Returns the number of element in the set.
  7217.  
  7218.      : union-set ( set1 set2 -- )
  7219.           The elements of "set1" are appended to the "set2". "set2" becomes
  7220.           the union of the sets.
  7221.  
  7222.      : { ( -- ) execution
  7223.           Used in the following form:
  7224.           { <_e_n_t_r_i_e_s> } ( -- set)
  7225.           to mark the beginning of a constant set of vocabulary entries.
  7226.  
  7227.      : } ( -- set) immediate
  7228.           Used in the following form:
  7229.           { <_e_n_t_r_i_e_s> } ( -- set)
  7230.           to mark the end of a constant set of vocabulary entries.
  7231.  
  7232.    INTERNALS
  7233.      The _s_e_t_s library contains the following internal function to search a
  7234.      set.
  7235.  
  7236.      : search-set ( element set -- [addr1] or [element addr2 false])
  7237.           Searches the set for the element. Returns the address, "add1", of
  7238.           the element if found else the element together with the last
  7239.           address, "addr2", and the flag, "false", is returned. Used to
  7240.           implement the functions "add-set", "remove-set", "?member-set" and
  7241.           "intersection-set".
  7242.  
  7243.    SEE ALSO
  7244.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _b_l_o_c_k_s(_3_X).
  7245.  
  7246.    NOTE
  7247.      The function list is sorted in ASCII order. The type and mode of the
  7248.      entry is indicated together with the parameter stack effect.
  7249.  
  7250.    COPYING
  7251.      Copyright (C) 1990 Mikael R.K. Patel
  7252.  
  7253.      Permission is granted to make and distribute verbatim copies of this
  7254.      manual provided the copyright notice and this permission notice are
  7255.  
  7256.  
  7257.    110
  7258.  
  7259.  
  7260.  
  7261.  
  7262.  
  7263.  
  7264.    August 7, 1990                                                    SETS(3X)
  7265.  
  7266.  
  7267.      preserved on all copies.
  7268.  
  7269.      Permission is granted to copy and distribute modified versions of this
  7270.      manual under the conditions for verbatim copying, provided also that the
  7271.      section entitled "GNU General Public License" is included exactly as in
  7272.      the original, and provided that the entire resulting derived work is
  7273.      distributed under the terms of a permission notice identical to this
  7274.      one.
  7275.  
  7276.      Permission is granted to copy and distribute translations of this manual
  7277.      into another language, under the above conditions for modified versions,
  7278.      except that the section entitled "GNU General Public License" may be
  7279.      included in a translation approved by the author instead of in the ori-
  7280.      ginal English.
  7281.  
  7282.    AUTHOR
  7283.      Mikael R.K. Patel
  7284.      Computer Aided Design Laboratory (CADLAB)
  7285.      Department of Computer and Information Science
  7286.      Linkoping University
  7287.      S-581 83 LINKOPING
  7288.      SWEDEN
  7289.      Email: mip@ida.liu.se
  7290.  
  7291.  
  7292.  
  7293.  
  7294.  
  7295.  
  7296.  
  7297.  
  7298.  
  7299.  
  7300.  
  7301.  
  7302.  
  7303.  
  7304.  
  7305.  
  7306.  
  7307.  
  7308.  
  7309.  
  7310.  
  7311.  
  7312.  
  7313.  
  7314.  
  7315.  
  7316.  
  7317.  
  7318.  
  7319.  
  7320.  
  7321.  
  7322.  
  7323.                                                                           111
  7324.  
  7325.  
  7326.  
  7327.  
  7328.  
  7329.  
  7330.    STACKS(3X)                                                  August 1, 1990
  7331.  
  7332.  
  7333.  
  7334.    NAME
  7335.      stacks - vector representation of stacks
  7336.  
  7337.    SYNOPSIS
  7338.      #include stacks.f83
  7339.  
  7340.      stacks
  7341.  
  7342.    DESCRIPTION
  7343.      Library for stacks represented as a vector. This library allows defini-
  7344.      tion and manipulation of "cell" width stacks. Provides functions for
  7345.      overflow and empty checking. Applications are required to check stack
  7346.      consistency with these functions.
  7347.  
  7348.      : .stack ( stack -- )
  7349.           Displays the contents of a stack in the following form:
  7350.           stack# <_s_t_a_c_k-_a_d_d_r_e_s_s> [ <_s_t_a_c_k-_d_e_p_t_h> ] / <_t_o_p> / ... / <_b_o_t_t_o_m>
  7351.  
  7352.      : ?empty-stack ( stack -- bool)
  7353.           Returns "true" if the stack is empty else "false".
  7354.  
  7355.      : ?full-stack ( stack -- bool)
  7356.           Returns "true" if the stack is full else "false".
  7357.  
  7358.      : ?map-stack ( stack block[element -- bool] -- )
  7359.           Conditional iterator for stacks. The parameter conditional block on
  7360.           each element on the stack starting with the top of stack and
  7361.           preceding towards the bottom of the stack. The conditional block
  7362.           should return a boolean flag for each call. The iterator is ter-
  7363.           minated when the block returns "true".
  7364.  
  7365.      struct.type STACK ( size -- )
  7366.           Used in the following form:
  7367.           <_s_i_z_e> STACK <_s_t_a_c_k-_n_a_m_e> ( -- stack)
  7368.           to create a stack variable. May also be used to create a unnamed
  7369.           stack instance with the "structures" library function "new-struct".
  7370.           In this case include the "structures" library and use the following
  7371.           form:
  7372.           <_s_i_z_e> new-struct STACK ( -- stack)
  7373.           The top of stack pointer is stored first in the "STACK" structure.
  7374.           <_s_t_a_c_k> @ @ ( -- element)
  7375.           This allows the top of stack element to be accessed indirectly
  7376.           through the stack variable. This action will copy the top of the
  7377.           stack to the forth parameter stack and not effect the internal
  7378.           stack pointers.
  7379.  
  7380.      : depth-stack ( stack -- num)
  7381.           Returns the stack depth. The return value represents the number of
  7382.           "pop" call that may be performed before the stack is empty.
  7383.  
  7384.      : empty-stack ( stack -- )
  7385.           Removes all elements from the stack by putting the stack top to be
  7386.           the stack bottom. The stack depth becomes zero and the stack
  7387.  
  7388.  
  7389.    112
  7390.  
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.    August 1, 1990                                                  STACKS(3X)
  7397.  
  7398.  
  7399.           becomes empty.
  7400.  
  7401.      : map-stack ( stack block[element -- ] -- )
  7402.           Stack iterator function. Calls the parameter block for each element
  7403.           in the stack starting with the top of stack and continues towards
  7404.           the bottom of the stack.
  7405.  
  7406.      : pop ( stack -- element)
  7407.           Removes the top element for the stack and returns this value. This
  7408.           function will not check if the stack is empty. Applying this func-
  7409.           tion on an empty stack will leave the stack in an error state.
  7410.  
  7411.      : push ( element stack -- )
  7412.           Appends the element to the top of the stack. This function will not
  7413.           check if the stack is full. Applying this function on an empty
  7414.           stack will leave the stack in an error state.
  7415.  
  7416.      : size-stack ( stack -- num)
  7417.           Return the maximum number of elements that the stack can contain.
  7418.  
  7419.      vocabulary stacks ( -- )
  7420.           Vocabulary containing the stack extensions. Include into the voca-
  7421.           bulary search structure, "context", to allow access of this
  7422.           library.
  7423.  
  7424.    INTERNALS
  7425.      Private definitions in the _s_t_a_c_k_s vocabulary;
  7426.  
  7427.      ptr +top ( stack -- addr) private
  7428.           Access field in "STACK" structure to pointer to top of stack.
  7429.  
  7430.      long +bytes ( stack -- addr) private
  7431.           Access field in "STACK" structure to size of stack area in bytes.
  7432.           The total size of a stack in bytes is the sum of the "STACK" struc-
  7433.           ture and this field. The size of the "STACK" header may be accessed
  7434.           with the function "sizeof" in the "structures" library.
  7435.  
  7436.      ptr +bottom ( stack --- addr) private
  7437.           Access field in "STACK" structure to pointer to bottom of stack.
  7438.  
  7439.    SEE ALSO
  7440.      _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X).
  7441.  
  7442.    NOTE
  7443.      The function list is sorted in ASCII order. The type and mode of the
  7444.      entries are indicated together with their parameter stack effect.
  7445.  
  7446.    COPYING
  7447.      Copyright (C) 1990 Mikael R.K. Patel
  7448.  
  7449.      Permission is granted to make and distribute verbatim copies of this
  7450.      manual provided the copyright notice and this permission notice are
  7451.      preserved on all copies.
  7452.  
  7453.  
  7454.  
  7455.                                                                           113
  7456.  
  7457.  
  7458.  
  7459.  
  7460.  
  7461.  
  7462.    STACKS(3X)                                                  August 1, 1990
  7463.  
  7464.  
  7465.      Permission is granted to copy and distribute modified versions of this
  7466.      manual under the conditions for verbatim copying, provided also that the
  7467.      section entitled "GNU General Public License" is included exactly as in
  7468.      the original, and provided that the entire resulting derived work is
  7469.      distributed under the terms of a permission notice identical to this
  7470.      one.
  7471.  
  7472.      Permission is granted to copy and distribute translations of this manual
  7473.      into another language, under the above conditions for modified versions,
  7474.      except that the section entitled "GNU General Public License" may be
  7475.      included in a translation approved by the author instead of in the ori-
  7476.      ginal English.
  7477.  
  7478.    AUTHOR
  7479.      Mikael R.K. Patel
  7480.      Computer Aided Design Laboratory (CADLAB)
  7481.      Department of Computer and Information Science
  7482.      Linkoping University
  7483.      S-581 83 LINKOPING
  7484.      SWEDEN
  7485.      Email: mip@ida.liu.se
  7486.  
  7487.  
  7488.  
  7489.  
  7490.  
  7491.  
  7492.  
  7493.  
  7494.  
  7495.  
  7496.  
  7497.  
  7498.  
  7499.  
  7500.  
  7501.  
  7502.  
  7503.  
  7504.  
  7505.  
  7506.  
  7507.  
  7508.  
  7509.  
  7510.  
  7511.  
  7512.  
  7513.  
  7514.  
  7515.  
  7516.  
  7517.  
  7518.  
  7519.  
  7520.  
  7521.    114
  7522.  
  7523.  
  7524.  
  7525.  
  7526.  
  7527.  
  7528.    September 7, 1990                                               STRING(3X)
  7529.  
  7530.  
  7531.  
  7532.    NAME
  7533.      string - tile kernel null-terminated string functions
  7534.  
  7535.    SYNOPSIS
  7536.      string
  7537.  
  7538.    DESCRIPTION
  7539.      The _t_i_l_e forth kernel support word set for null-terminated strings.
  7540.      Used by the kernel to maintain strings in vocabularies, etc.  Strings
  7541.      are not allocated from the forth dictionary.
  7542.  
  7543.      code " ( -- str) immediate
  7544.           Used in the following form:
  7545.           " <_a_n_y-_s_t_r_i_n_g> "
  7546.           to compile a string literal. A string is not bounded by any size as
  7547.           it is null terminated. A double quote character cannot be part of
  7548.           the string.
  7549.  
  7550.      code $print ( str -- )
  7551.           Displays a string on the current output device.
  7552.  
  7553.      code $allot ( n -- str)
  7554.           Allocates storage for a string of max length "n". The string may be
  7555.           reclaimed with the function "$free".
  7556.  
  7557.      code $cat ( str1 str2 -- )
  7558.           Concatenates "str2" to "str1" and returns the pointer to "str2".
  7559.           "str2" is assumed to have space for "str1" and should have a
  7560.           minimum length of both strings.
  7561.  
  7562.      code $dup ( str1 -- str1 str2)
  7563.           Returns copy of the parameter string. The copy is equivalent to the
  7564.           parameter but is allocated to another memory area. The copy should
  7565.           be reclaimed with the function "$free".
  7566.  
  7567.      code $equal ( str1 str2 -- bool)
  7568.           Compares the two strings and returns "true" if they are equal else
  7569.           "false".
  7570.  
  7571.      code $free ( str -- )
  7572.           Returns allocated string storage to the run-time heap.
  7573.  
  7574.      code $length ( str -- num)
  7575.           Returns the length of the string not counting the null character
  7576.           terminating the string. A string may have zero length.
  7577.  
  7578.      code (") ( -- str) compilation
  7579.           Compiled run-time action for string literal. Pushes a pointer to
  7580.           the inline string onto the parameter stack. Compiled by the word
  7581.           """.
  7582.  
  7583.      vocabulary string ( -- )
  7584.           Vocabulary containing the null-terminated string definitions.
  7585.  
  7586.  
  7587.                                                                           115
  7588.  
  7589.  
  7590.  
  7591.  
  7592.  
  7593.  
  7594.    STRING(3X)                                               September 7, 1990
  7595.  
  7596.  
  7597.           Include into the vocabulary search structure, "context", to allow
  7598.           access to these extensions.
  7599.  
  7600.    SEE ALSO
  7601.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  7602.  
  7603.    NOTE
  7604.      The function list is sorted in ASCII order. The type and mode of the
  7605.      entries are indicated together with their parameter stack effect.
  7606.  
  7607.    COPYING
  7608.      Copyright (C) 1990 Mikael R.K. Patel
  7609.  
  7610.      Permission is granted to make and distribute verbatim copies of this
  7611.      manual provided the copyright notice and this permission notice are
  7612.      preserved on all copies.
  7613.  
  7614.      Permission is granted to copy and distribute modified versions of this
  7615.      manual under the conditions for verbatim copying, provided also that the
  7616.      section entitled "GNU General Public License" is included exactly as in
  7617.      the original, and provided that the entire resulting derived work is
  7618.      distributed under the terms of a permission notice identical to this
  7619.      one.
  7620.  
  7621.      Permission is granted to copy and distribute translations of this manual
  7622.      into another language, under the above conditions for modified versions,
  7623.      except that the section entitled "GNU General Public License" may be
  7624.      included in a translation approved by the author instead of in the ori-
  7625.      ginal English.
  7626.  
  7627.    AUTHOR
  7628.      Mikael R.K. Patel
  7629.      Computer Aided Design Laboratory (CADLAB)
  7630.      Department of Computer and Information Science
  7631.      Linkoping University
  7632.      S-581 83 LINKOPING
  7633.      SWEDEN
  7634.      Email: mip@ida.liu.se
  7635.  
  7636.  
  7637.  
  7638.  
  7639.  
  7640.  
  7641.  
  7642.  
  7643.  
  7644.  
  7645.  
  7646.  
  7647.  
  7648.  
  7649.  
  7650.  
  7651.  
  7652.  
  7653.    116
  7654.  
  7655.  
  7656.  
  7657.  
  7658.  
  7659.  
  7660.    August 6, 1990                                              STRUCTURES(3X)
  7661.  
  7662.  
  7663.  
  7664.    NAME
  7665.      structures - aggregated data definitions
  7666.  
  7667.    SYNOPSIS
  7668.      #include structures.f83
  7669.  
  7670.      structures
  7671.  
  7672.    DESCRIPTION
  7673.      Allows composition of data field description to build structures.  A
  7674.      basic language extension library in the _t_i_l_e forth kernel and used
  7675.      throughout the source code library to describe data structures. The
  7676.      "structures" package extends the traditional "record" or "structure"
  7677.      concept and allows initialization and high level management code to be
  7678.      defined together with the structure itself.
  7679.  
  7680.      : align ( -- )
  7681.           Used within a structure type field definition section to align the
  7682.           current field address to an even address.
  7683.  
  7684.      : as ( -- struct.type) immediate
  7685.           Used in the following form:
  7686.           as <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> ( -- struct.type)
  7687.           Returns the address of the body of the structure type information.
  7688.           This address may be passed to the structure instance initialization
  7689.           function, "initiate".
  7690.  
  7691.      : assign ( x y -- ) immediate
  7692.           Used in the following form:
  7693.           _x _y assign <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e>
  7694.           or
  7695.           _x _y assign <_p_r_i_m-_t_y_p_e-_n_a_m_e>
  7696.           Assigns the structure or primitive pointed to by "y" the value of
  7697.           "x". The primitive types are equivalent to the structure type field
  7698.           names, "byte", "word", "long", "ptr" and "enum".
  7699.  
  7700.      struct.field byte ( -- )
  7701.           Used in the following form:
  7702.           byte <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2)
  7703.           within a structure type definition section to create an access
  7704.           field name to a byte.
  7705.  
  7706.      : bytes ( n -- )
  7707.           Used in the following form:
  7708.           <_n_u_m_b_e_r> bytes <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2)
  7709.           within a structure type definition section to create a field access
  7710.           name to a given <_n_u_m_b_e_r> of bytes.
  7711.  
  7712.      struct.field enum ( -- )
  7713.           Used in the following form:
  7714.           enum <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2)
  7715.           within a structure type definition section to create a field access
  7716.           name to an enumerate. The size of an enumerate field is four bytes.
  7717.  
  7718.  
  7719.                                                                           117
  7720.  
  7721.  
  7722.  
  7723.  
  7724.  
  7725.  
  7726.    STRUCTURES(3X)                                              August 6, 1990
  7727.  
  7728.  
  7729.      : initiate ( addr struct.type -- )
  7730.           Used in the following form:
  7731.           <_i_n_s_t_a_n_c_e> as <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> initiate
  7732.           Take a pointer to a memory area and initializes it according to the
  7733.           initialization code for the structure type given as the second
  7734.           parameter. Parameters to this code section can be passed as usual
  7735.           on the parameter stack.
  7736.  
  7737.      struct.field long ( -- )
  7738.           Used in the following form:
  7739.           long <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2)
  7740.           within a structure type definition section to create a field access
  7741.           name to a long number. The size of a long is four bytes.
  7742.  
  7743.      : new-struct ( -- addr) immediate
  7744.           Used in the following form:
  7745.           new-struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> ( -- addr)
  7746.           to allocate and initialize an instance of a structure type. A
  7747.           pointer to the instance is returned. The instance is not bound to
  7748.           any variable.
  7749.  
  7750.      : not-equal ( x y -- bool) immediate
  7751.           Used in the following form:
  7752.           _x _y not-equal <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e>
  7753.           or
  7754.           _x _y not-equal <_p_r_i_m-_t_y_p_e-_n_a_m_e>
  7755.           to compare two structure instances. The primitive types are
  7756.           equivalent to the structure type field names, "byte", "word",
  7757.           "long", "ptr" and "enum".
  7758.  
  7759.      struct.field ptr ( -- )
  7760.           Used in the following form:
  7761.           ptr <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2)
  7762.           within a structure type definition section to create a field access
  7763.           name to a pointer. The size of a pointer is four bytes.
  7764.  
  7765.      : sizeof ( -- num) immediate
  7766.           Used in the following forms:
  7767.           sizeof <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e>
  7768.           or
  7769.           sizeof <_p_r_i_m-_t_y_p_e-_n_a_m_e>
  7770.           Returns the size, in bytes, of a structure or primitive type. The
  7771.           primitive types are "byte", "word", "long", "ptr" and "enum".
  7772.  
  7773.      : struct ( -- )
  7774.           Used in the following form:
  7775.           struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2)
  7776.           within a structure type definition section to create a field access
  7777.           name to a structure. The structure is not initialized automatically
  7778.           by the structure type. This should be performed by the initializa-
  7779.           tion code of the structure type it is a part of. This may be per-
  7780.           formed with the words "as" and "initiate". Remember to pass neces-
  7781.           sary parameters to the initialization code.
  7782.  
  7783.  
  7784.  
  7785.    118
  7786.  
  7787.  
  7788.  
  7789.  
  7790.  
  7791.  
  7792.    August 6, 1990                                              STRUCTURES(3X)
  7793.  
  7794.  
  7795.      : struct.does ( addr -- ) immediate compilation
  7796.           Used within a structure type definition section to define the end
  7797.           of the structure layout or initialization code and the beginning of
  7798.           the instance action code. At run-time, performed for entry bounded
  7799.           (named) instance, the code receives a pointer to the instance as
  7800.           parameter.
  7801.  
  7802.      : struct.end ( -- ) immediate
  7803.           Used to terminate a structure type definition.
  7804.  
  7805.      : struct.init ( addr -- )
  7806.           Used within a structure type definition section to terminate the
  7807.           structure layout and the beginning the definition of the initiali-
  7808.           zation
  7809.            code section. At run-time the code receives a pointer to the
  7810.           instance as a parameter.
  7811.  
  7812.      : struct.type ( -- )
  7813.           Used in the following forms:
  7814.           struct.type <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> ( ... -- )
  7815.           <_s_t_r_u_c_t-_t_y_p_e-_l_a_y_o_u_t>
  7816.           struct.init ( ... addr -- ...)
  7817.           <_i_n_i_t_i_a_l_i_z_a_t_i_o_n-_p_a_r_t>
  7818.           struct.does ( ... addr -- ...)
  7819.           <_i_n_s_t_a_n_c_e-_p_a_r_t>
  7820.           struct.end
  7821.           and then:
  7822.           <struct-type-name> <_i_n_s_t_a_n_c_e-_n_a_m_e>
  7823.           Starts the definition of a structure type. The layout section
  7824.           <_s_t_r_u_c_t-_t_y_p_e-_l_a_y_o_u_t> may contain the words; <_n> bytes <_f_i_e_l_d-_n_a_m_e>,
  7825.           allocates "n" bytes, byte <_f_i_e_l_d-_n_a_m_e>, a byte, word <_f_i_e_l_d-_n_a_m_e>,
  7826.           a word, long <_f_i_e_l_d-_n_a_m_e>, a long, ptr <_f_i_e_l_d-_n_a_m_e>, a pointer,
  7827.           enum <_f_i_e_l_d-_n_a_m_e>, an enumerative, and struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e>
  7828.           <_f_i_e_l_d-_n_a_m_e>, a structure. To align a field to even address use
  7829.           "align".  The initialization code receives a pointer to the block
  7830.           to initialize and any additional parameters. Thus additional memory
  7831.           may be allocated directly after the block. If the structure con-
  7832.           tains structure fields these should be initialized by the initiali-
  7833.           zation code. For this "as" and "initiate" are used; <_i_n_s_t_a_n_c_e> as
  7834.           <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> initiate. The normal action performed by a
  7835.           instance of a structure type is to return the address to the
  7836.           instance. The optional "struct.does" part redefines the normal
  7837.           action of a created structure block. It receives a pointer to the
  7838.           instance as parameter and any additional parameters. The sections
  7839.           "struct.init" and "struct.does" are optional.
  7840.  
  7841.      vocabulary structures ( -- )
  7842.           Vocabulary for structure type extensions. Include into the vocabu-
  7843.           lary search structure, "context", to allow use of structures and
  7844.           description of aggregated data structures.
  7845.  
  7846.      : this ( -- addr)
  7847.           Returns the compilation address of the latest defined word.
  7848.  
  7849.  
  7850.  
  7851.                                                                           119
  7852.  
  7853.  
  7854.  
  7855.  
  7856.  
  7857.  
  7858.    STRUCTURES(3X)                                              August 6, 1990
  7859.  
  7860.  
  7861.      struct.field word ( -- )
  7862.           Used in the following form:
  7863.           word <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2)
  7864.           within a structure type definition to create a field access name to
  7865.           a word. The size of a word is two bytes.
  7866.  
  7867.    INTERNALS
  7868.      Private definitions in the _s_t_r_u_c_t_u_r_e_s vocabulary;
  7869.  
  7870.      field +size ( struct.type -- addr) private
  7871.           Field for accessing the size of a structure type. This field is a
  7872.           long containing the number of bytes to allocate for an instance of
  7873.           the structure type.
  7874.  
  7875.      field +initiate ( struct.type -- addr) private
  7876.           Field for accessing the initialization code of a structure type.
  7877.           This field is a "ptr" containing a pointer to the initialization
  7878.           code for the structure type. A zero value, "nil", indicates that
  7879.           the structure type does not perform initialization.
  7880.  
  7881.      : struct.field ( bytes -- ) private
  7882.           Used in the following form:
  7883.           <_b_y_t_e_s> struct.field <_f_i_e_l_d-_t_y_p_e-_n_a_m_e>
  7884.           to create additional field types other than "byte" etc.
  7885.  
  7886.      : make-struct ( struct.type -- addr) private
  7887.           Given a pointer to a structure type information block, as generated
  7888.           by "as", allocates memory in the dictionary and initializes it.
  7889.           Returns a pointer to the created instance.
  7890.  
  7891.    SEE ALSO
  7892.      _t_i_l_e(_1), _f_o_r_t_h(_3_X).
  7893.  
  7894.    EXAMPLES
  7895.      An example showing how to defined a list structure:
  7896.  
  7897.           struct.type LIST ( -- )
  7898.                ptr +next ( list -- addr)
  7899.           struct.init ( list -- )
  7900.                nil swap +next !
  7901.           struct.end
  7902.  
  7903.           sizeof LIST .
  7904.           new-struct LIST constant x
  7905.  
  7906.           LIST y
  7907.  
  7908.    NOTE
  7909.      The function list is sorted in ASCII order. The type and mode of the
  7910.      entries are indicated together with their parameter stack effect.
  7911.  
  7912.      The "structures" library optimizes the first field so that access
  7913.      becomes an immediate word with no effect. The most common accessed field
  7914.      should be placed first in a "structure" definition.
  7915.  
  7916.  
  7917.    120
  7918.  
  7919.  
  7920.  
  7921.  
  7922.  
  7923.  
  7924.    August 6, 1990                                              STRUCTURES(3X)
  7925.  
  7926.  
  7927.  
  7928.    COPYING
  7929.      Copyright (C) 1990 Mikael R.K. Patel
  7930.  
  7931.      Permission is granted to make and distribute verbatim copies of this
  7932.      manual provided the copyright notice and this permission notice are
  7933.      preserved on all copies.
  7934.  
  7935.      Permission is granted to copy and distribute modified versions of this
  7936.      manual under the conditions for verbatim copying, provided also that the
  7937.      section entitled "GNU General Public License" is included exactly as in
  7938.      the original, and provided that the entire resulting derived work is
  7939.      distributed under the terms of a permission notice identical to this
  7940.      one.
  7941.  
  7942.      Permission is granted to copy and distribute translations of this manual
  7943.      into another language, under the above conditions for modified versions,
  7944.      except that the section entitled "GNU General Public License" may be
  7945.      included in a translation approved by the author instead of in the ori-
  7946.      ginal English.
  7947.  
  7948.    AUTHOR
  7949.      Mikael R.K. Patel
  7950.      Computer Aided Design Laboratory (CADLAB)
  7951.      Department of Computer and Information Science
  7952.      Linkoping University
  7953.      S-581 83 LINKOPING
  7954.      SWEDEN
  7955.      Email: mip@ida.liu.se
  7956.  
  7957.  
  7958.  
  7959.  
  7960.  
  7961.  
  7962.  
  7963.  
  7964.  
  7965.  
  7966.  
  7967.  
  7968.  
  7969.  
  7970.  
  7971.  
  7972.  
  7973.  
  7974.  
  7975.  
  7976.  
  7977.  
  7978.  
  7979.  
  7980.  
  7981.  
  7982.  
  7983.                                                                           121
  7984.  
  7985.  
  7987.